add custom header support

docs/api.md

@@ -55,8 +55,8 @@ var markdownProcessor = new MarkdownProcessor(
     snippets: snippets.ToDictionary(),
     appendSnippetGroup: SimpleSnippetMarkdownHandling.AppendGroup,
     snippetSourceFiles: new List<string>(),
-    writeHeader: true,
-    tocLevel: 2);
+    tocLevel: 2,
+    writeHeader: true);
 
 var path = @"C:\path\inputMarkdownFile.md";
 using (var reader = File.OpenText(path))

docs/config-file.md

@@ -14,14 +14,15 @@ Add a file named `mdsnippets.json` at the target directory with the following co
 <!-- snippet: sampleConfig.json -->
 ```json
 {
-  "WriteHeader": true,
   "ReadOnly": false,
   "LinkFormat": "Tfs",
   "TocLevel": 3,
   "Exclude": [ "Dir1", "Dir2" ],
   "UrlsAsSnippets": [ "Url1", "Url2" ],
-  "TocExcludes": [ "Exclude Heading1", "Exclude Heading2" ]
+  "TocExcludes": [ "Exclude Heading1", "Exclude Heading2" ],
+  "WriteHeader": true,
+  "Header": "GENERATED FILE - Source File: {relativePath}"
 }
 ```
-<sup>[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L9)</sup>
+<sup>[snippet source](/src/ConfigReader.Tests/sampleConfig.json#L1-L10)</sup>
 <!-- endsnippet -->

readme.md

@@ -27,6 +27,7 @@ A [dotnet tool](https://docs.microsoft.com/en-us/dotnet/core/tools/global-tools)
   * [Snippet Exclusions](#snippet-exclusions)
   * [Mark resulting files as read only](#mark-resulting-files-as-read-only)
   * [Table of contents](#table-of-contents)
+  * [Header](#header)
   * [LinkFormat](#linkformat)
 <!-- endtoc -->
 
@@ -215,6 +216,32 @@ To exclude headings use the `--toc-excludes` argument. So for example to exclude
 mdsnippets --toc-excludes heading1:heading2
 ```
 
+## Header
+
+When a .md file is written, a header is include. The default header is:
+
+<!-- snippet: HeaderWriterTests.DefaultHeader.approved.txt -->
+```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>
+<!-- endsnippet -->
+
+To disable the header use '--write-header'
+
+```ps
+mdsnippets --write-header false
+```
+
+To apply a custom header use '--header'
+
+```ps
+mdsnippets --header 'GENERATED FILE - Source File: {relativePath}'
+```
+
 
 ## LinkFormat
 

readme.source.md

@@ -161,6 +161,24 @@ To exclude headings use the `--toc-excludes` argument. So for example to exclude
 mdsnippets --toc-excludes heading1:heading2
 ```
 
+## Header
+
+When a .md file is written, a header is include. The default header is:
+
+snippet: HeaderWriterTests.DefaultHeader.approved.txt
+
+To disable the header use '--write-header'
+
+```ps
+mdsnippets --write-header false
+```
+
+To apply a custom header use '--header'
+
+```ps
+mdsnippets --header 'GENERATED FILE - Source File: {relativePath}'
+```
+
 
 ## LinkFormat
 

src/ConfigReader.Tests/ConfigReaderTests.Values.approved.txt

@@ -1,5 +1,4 @@
 {
-  WriteHeader: true,
   ReadOnly: false,
   LinkFormat: 'Tfs',
   TocLevel: 3,
@@ -11,6 +10,8 @@
     'Dir1',
     'Dir2'
   ],
+  WriteHeader: true,
+  Header: 'GENERATED FILE - Source File: {relativePath}',
   TocExcludes: [
     'Exclude Heading1',
     'Exclude Heading2'

src/ConfigReader.Tests/sampleConfig.json

@@ -1,9 +1,10 @@
 {
-  "WriteHeader": true,
   "ReadOnly": false,
   "LinkFormat": "Tfs",
   "TocLevel": 3,
   "Exclude": [ "Dir1", "Dir2" ],
   "UrlsAsSnippets": [ "Url1", "Url2" ],
-  "TocExcludes": [ "Exclude Heading1", "Exclude Heading2" ]
+  "TocExcludes": [ "Exclude Heading1", "Exclude Heading2" ],
+  "WriteHeader": true,
+  "Header": "GENERATED FILE - Source File: {relativePath}"
 }

src/ConfigReader/ConfigDefaults.cs

@@ -14,6 +14,7 @@ public static ConfigResult Convert(ConfigInput fileConfig, ConfigInput otherConf
                 WriteHeader = otherConfig.WriteHeader.GetValueOrDefault(true),
                 LinkFormat = otherConfig.LinkFormat.GetValueOrDefault(LinkFormat.GitHub),
                 Exclude = otherConfig.Exclude,
+                Header = otherConfig.Header,
                 TocExcludes = otherConfig.TocExcludes,
                 UrlsAsSnippets = otherConfig.UrlsAsSnippets,
                 TocLevel = otherConfig.TocLevel.GetValueOrDefault(2)
@@ -26,6 +27,7 @@ public static ConfigResult Convert(ConfigInput fileConfig, ConfigInput otherConf
             WriteHeader = GetValueOrDefault("WriteHeader", otherConfig.WriteHeader, fileConfig.WriteHeader, true),
             LinkFormat = GetValueOrDefault("LinkFormat", otherConfig.LinkFormat, fileConfig.LinkFormat, LinkFormat.GitHub),
             TocLevel = GetValueOrDefault("TocLevel", otherConfig.TocLevel, fileConfig.TocLevel, 2),
+            Header = GetValueOrDefault("Header", otherConfig.Header, fileConfig.Header),
             Exclude = JoinLists(fileConfig.Exclude, otherConfig.Exclude),
             TocExcludes = JoinLists(fileConfig.TocExcludes, otherConfig.TocExcludes),
             UrlsAsSnippets = JoinLists(fileConfig.UrlsAsSnippets, otherConfig.UrlsAsSnippets)
@@ -60,4 +62,19 @@ static T GetValueOrDefault<T>(string name, T? input, T? config, T defaultValue)
 
         return defaultValue;
     }
+
+    static string GetValueOrDefault(string name, string input, string config)
+    {
+        if (input != null && config != null)
+        {
+            throw new ConfigurationException($"'{name}' cannot be defined in both mdsnippets.json and input");
+        }
+
+        if (input != null)
+        {
+            return input;
+        }
+
+        return config;
+    }
 }

src/ConfigReader/ConfigInput.cs

@@ -3,11 +3,12 @@
 
 public class ConfigInput
 {
-    public bool? WriteHeader { get; set; }
     public bool? ReadOnly { get; set; }
     public LinkFormat? LinkFormat { get; set; }
     public int? TocLevel { get; set; }
     public List<string> UrlsAsSnippets { get; set; } = new List<string>();
     public List<string> Exclude { get; set; } = new List<string>();
+    public bool? WriteHeader { get; set; }
+    public string Header { get; set; }
     public List<string> TocExcludes { get; set; } = new List<string>();
 }

src/ConfigReader/ConfigReader.cs

@@ -30,6 +30,7 @@ public static ConfigInput Parse(string contents)
                 ReadOnly = configSerialization.ReadOnly,
                 UrlsAsSnippets = configSerialization.UrlsAsSnippets,
                 Exclude = configSerialization.Exclude,
+                Header = configSerialization.Header,
                 TocExcludes = configSerialization.TocExcludes,
                 TocLevel = configSerialization.TocLevel,
                 LinkFormat = GetLinkFormat(configSerialization.LinkFormat),

src/ConfigReader/ConfigResult.cs

@@ -4,10 +4,11 @@
 public class ConfigResult
 {
     public bool ReadOnly;
-    public bool WriteHeader;
     public LinkFormat LinkFormat;
     public int TocLevel;
     public List<string> UrlsAsSnippets = new List<string>();
     public List<string> Exclude = new List<string>();
+    public bool WriteHeader;
+    public string Header;
     public List<string> TocExcludes = new List<string>();
 }

src/ConfigReader/ConfigSerialization.cs

@@ -2,9 +2,10 @@
 
 public class ConfigSerialization
 {
-    public bool? WriteHeader { get; set; }
     public bool? ReadOnly { get; set; }
     public string LinkFormat { get; set; }
+    public bool? WriteHeader { get; set; }
+    public string Header { get; set; }
     public int? TocLevel { get; set; }
     public List<string> UrlsAsSnippets { get; set; } = new List<string>();
     public List<string> Exclude { get; set; } = new List<string>();

src/ConfigReader/LogBuilder.cs

@@ -10,6 +10,7 @@ public static string BuildConfigLogMessage(string root, ConfigResult config, str
     RootDir: {root}
     ReadOnly: {config.ReadOnly}
     WriteHeader: {config.WriteHeader}
+    Header: {config.Header}
     LinkFormat: {config.LinkFormat}
     TocLevel: {config.TocLevel}
     FileConfigPath: {configFilePath} (exists:{File.Exists(configFilePath)})

src/Directory.Build.props

@@ -5,7 +5,7 @@
     <LangVersion>latest</LangVersion>
     <NoWarn>CS1591</NoWarn>
     <NoPackageAnalysis>true</NoPackageAnalysis>
-    <Version>15.1.1</Version>
+    <Version>16.0.0</Version>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <Copyright>Copyright $([System.DateTime]::UtcNow.ToString(yyyy)). All rights reserved</Copyright>
     <PackageIconUrl>https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/src/icon.png</PackageIconUrl>

src/MarkdownSnippets.MsBuild/DocoTask.cs

@@ -14,6 +14,7 @@ public class DocoTask :
         public string ProjectDirectory { get; set; }
         public bool? ReadOnly { get; set; }
         public bool? WriteHeader { get; set; }
+        public string Header { get; set; }
         public int? TocLevel { get; set; }
         public LinkFormat? LinkFormat { get; set; }
         public List<string> Exclude { get; set; } = new List<string>();
@@ -32,6 +33,7 @@ public override bool Execute()
                 {
                     ReadOnly = ReadOnly,
                     WriteHeader = WriteHeader,
+                    Header = Header,
                     LinkFormat = LinkFormat,
                     Exclude = Exclude,
                     TocExcludes = TocExcludes,
@@ -48,6 +50,7 @@ public override bool Execute()
                 readOnly: configResult.ReadOnly,
                 directoryFilter: ExcludeToFilterBuilder.ExcludesToFilter(configResult.Exclude),
                 writeHeader: configResult.WriteHeader,
+                header: configResult.Header,
                 linkFormat: configResult.LinkFormat,
                 tocLevel: configResult.TocLevel,
                 tocExcludes: configResult.TocExcludes);

src/MarkdownSnippets.Tool/CommandRunner.cs

@@ -28,6 +28,7 @@ public static void RunCommand(Invoke invoke, params string[] args)
                     {
                         ReadOnly = options.ReadOnly,
                         WriteHeader = options.WriteHeader,
+                        Header = options.Header,
                         LinkFormat = options.LinkFormat,
                         TocLevel = options.TocLevel,
                         Exclude = options.Exclude.ToList(),
@@ -40,6 +41,11 @@ public static void RunCommand(Invoke invoke, params string[] args)
 
     static void ValidateAndApplyDefaults(Options options)
     {
+        if (options.Header != null && string.IsNullOrWhiteSpace(options.Header))
+        {
+            throw new CommandLineException("Empty Header is not allowed.");
+        }
+
         if (options.TargetDirectory == null)
         {
             options.TargetDirectory = Environment.CurrentDirectory;
@@ -61,6 +67,7 @@ static void ValidateAndApplyDefaults(Options options)
         {
             throw new CommandLineException("toc-level must be positive.");
         }
+
         ValidateItems("exclude", options.Exclude);
         ValidateItems("toc-excludes", options.TocExcludes);
         ValidateItems("urls-as-snippets", options.UrlsAsSnippets);

src/MarkdownSnippets.Tool/Options.cs

@@ -32,11 +32,17 @@ public class Options
         HelpText = "Set resultant md files as read-only. Optional. Defaults to false.")]
     public bool? ReadOnly { get; set; }
 
-    [Option('h', "write-header",
+    [Option("write-header",
         Required = false,
         HelpText = "Write a header at the top of each resultant md file. Optional. Defaults to true")]
     public bool? WriteHeader { get; set; }
 
+    [Option("header",
+        Required = false,
+        HelpText = @"The header to write. `{relativePath}` is replaced with the current .source.md file. Optional. Defaults to:
+" + HeaderWriter.DefaultHeader)]
+    public string Header { get; set; }
+
     [Option('l', "link-format",
         Required = false,
         HelpText = "Controls the format of the link under each snippet. Optional. Supported values: GitHub, Tfs. Defaults to GitHub.")]

src/MarkdownSnippets.Tool/Program.cs

@@ -31,6 +31,7 @@ static void Inner(string targetDirectory, ConfigInput configInput)
             directoryFilter: ExcludeToFilterBuilder.ExcludesToFilter(configResult.Exclude),
             readOnly: configResult.ReadOnly,
             writeHeader: configResult.WriteHeader,
+            header: configResult.Header,
             linkFormat: configResult.LinkFormat,
             tocExcludes: configResult.TocExcludes,
             tocLevel: configResult.TocLevel);

src/MarkdownSnippets/AssemblyInfo.cs

@@ -1,3 +1,4 @@
 using System.Runtime.CompilerServices;
 
-[assembly: InternalsVisibleTo("Tests, PublicKey=0024000004800000940000000602000000240000525341310004000001000100e191859fcd1deee68b96927c170783ced0c9a471a6424a0a011cfd31156a49dd73c4ad4a88b995fb918c0b43e0c005ef5fb72d53a328a64bde825cb5f2e4c53d66f69fcbb87d6737128b98e677a42091974b5f56093123a2dd6bc738af751b101d41c4f7a996e217b61967a3aa1ae7bc791d19c1cbeef47f0cdd20d288dff1a3")]
+[assembly: InternalsVisibleTo("Tests, PublicKey=0024000004800000940000000602000000240000525341310004000001000100e191859fcd1deee68b96927c170783ced0c9a471a6424a0a011cfd31156a49dd73c4ad4a88b995fb918c0b43e0c005ef5fb72d53a328a64bde825cb5f2e4c53d66f69fcbb87d6737128b98e677a42091974b5f56093123a2dd6bc738af751b101d41c4f7a996e217b61967a3aa1ae7bc791d19c1cbeef47f0cdd20d288dff1a3")]
+[assembly: InternalsVisibleTo("mdsnippets, PublicKey=0024000004800000940000000602000000240000525341310004000001000100e191859fcd1deee68b96927c170783ced0c9a471a6424a0a011cfd31156a49dd73c4ad4a88b995fb918c0b43e0c005ef5fb72d53a328a64bde825cb5f2e4c53d66f69fcbb87d6737128b98e677a42091974b5f56093123a2dd6bc738af751b101d41c4f7a996e217b61967a3aa1ae7bc791d19c1cbeef47f0cdd20d288dff1a3")]

src/MarkdownSnippets/Processing/DirectoryMarkdownProcessor.cs

@@ -9,6 +9,7 @@ namespace MarkdownSnippets
     public class DirectoryMarkdownProcessor
     {
         bool writeHeader;
+        string header;
         DirectoryFilter directoryFilter;
         bool readOnly;
         int tocLevel;
@@ -27,13 +28,15 @@ public class DirectoryMarkdownProcessor
             Action<string> log = null,
             AppendSnippetGroupToMarkdown appendSnippetGroup = null,
             bool writeHeader = true,
+            string header = null,
             DirectoryFilter directoryFilter = null,
             bool readOnly = false,
             LinkFormat linkFormat = LinkFormat.GitHub,
             int tocLevel = 2,
             IEnumerable<string> tocExcludes = null)
         {
             this.writeHeader = writeHeader;
+            this.header = header;
             this.directoryFilter = directoryFilter;
             this.readOnly = readOnly;
             this.tocLevel = tocLevel;
@@ -131,8 +134,9 @@ public void Run()
                 snippets.ToDictionary(),
                 appendSnippetGroup,
                 snippetSourceFiles,
-                writeHeader,
                 tocLevel,
+                writeHeader,
+                header,
                 tocExcludes);
             foreach (var sourceFile in sourceMdFiles)
             {

src/MarkdownSnippets/Processing/HeaderWriter.cs

@@ -1,20 +1,25 @@
-using System.Text;
-
-static class HeaderWriter
+static class HeaderWriter
 {
-    public static string WriteHeader(string relativePath)
+    internal const string DefaultHeader = @"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.";
+
+    public static string WriteHeader(string relativePath, string header)
     {
+        return $@"<!--
+{GetInner(relativePath, header)}
+-->
+";
+    }
 
-        var builder = new StringBuilder();
-        builder.AppendLine("<!--");
-        builder.AppendLine("GENERATED FILE - DO NOT EDIT");
-        builder.AppendLine("This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).");
-        if (relativePath != null)
+    static string GetInner(string relativePath, string header)
+    {
+        if (header == null)
         {
-            builder.AppendLine($"Source File: {relativePath}");
+            return DefaultHeader.Replace("{relativePath}", relativePath);
         }
-        builder.AppendLine("To change this file edit the source file and then run MarkdownSnippets.");
-        builder.AppendLine("-->");
-        return builder.ToString();
+
+        return header.Replace("{relativePath}", relativePath);
     }
 }