Fix to preserve line break after headers issue #319 (#321)

* Updates to preserve blank line after header #319

* Updates to preserve blank line after header for examples and parameters

* Updates to preserve parameter, input, output and to remove trailing line breaks related links

* Avoid adding 2 extra lines after parameter body

Author: BernieWhite

CHANGELOG.md

@@ -4,6 +4,7 @@ CHANGELOG
 ## Not released
 
 * Clean up trailing whitespace during markdown generation [#225](https://github.com/PowerShell/platyPS/issues/225)
+* Preserve line breaks after headers when Update-MarkdownHelp is used [#319](https://github.com/PowerShell/platyPS/issues/319)
 
 ## 0.8.3
 

src/Markdown.MAML/Markdown.MAML.csproj

@@ -61,6 +61,8 @@
     <Compile Include="Model\Markdown\MarkdownNode.cs" />
     <Compile Include="Model\Markdown\MarkdownNodeType.cs" />
     <Compile Include="Model\Markdown\ParagraphNode.cs" />
+    <Compile Include="Model\Markdown\SectionBody.cs" />
+    <Compile Include="Model\Markdown\SectionFormatOption.cs" />
     <Compile Include="Model\Markdown\SourceExtent.cs" />
     <Compile Include="Model\Markdown\TextNode.cs" />
     <Compile Include="Model\Markdown\HyperlinkSpan.cs" />

src/Markdown.MAML/Model/MAML/MamlCommand.cs

@@ -6,9 +6,12 @@ namespace Markdown.MAML.Model.MAML
     public class MamlCommand
     {
         public SourceExtent Extent { get; set; }
+
         public string Name { get; set; }
-        public string Synopsis { get; set; }
-        public string Description { get; set; }
+
+        public SectionBody Synopsis { get; set; }
+
+        public SectionBody Description { get; set; }
 
         public List<MamlInputOutput> Inputs 
         {
@@ -25,7 +28,7 @@ public List<MamlParameter> Parameters
             get { return _parameters; } 
         }
 
-        public string Notes { get; set; }
+        public SectionBody Notes { get; set; }
 
         public bool IsWorkflow { get; set; }
 

src/Markdown.MAML/Model/MAML/MamlExample.cs

@@ -1,4 +1,5 @@
-using System;
+using Markdown.MAML.Model.Markdown;
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
@@ -12,5 +13,10 @@ public class MamlExample
         public string Code { get; set; }
         public string Remarks { get; set; }
         public string Introduction { get; set; }
+
+        /// <summary>
+        /// Additional options that determine how the section will be formated when rendering markdown.
+        /// </summary>
+        public SectionFormatOption FormatOption { get; set; }
     }
 }

src/Markdown.MAML/Model/MAML/MamlInputOutput.cs

@@ -1,4 +1,5 @@
-using System;
+using Markdown.MAML.Model.Markdown;
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
@@ -14,6 +15,11 @@ public class MamlInputOutput : IEquatable<MamlInputOutput>
         public string TypeName { get; set; }
         public string Description { get; set; }
 
+        /// <summary>
+        /// Additional options that determine how the section will be formated when rendering markdown.
+        /// </summary>
+        public SectionFormatOption FormatOption { get; set; }
+
         bool IEquatable<MamlInputOutput>.Equals(MamlInputOutput other)
         {
             if (!StringComparer.OrdinalIgnoreCase.Equals(other.TypeName, this.TypeName))

src/Markdown.MAML/Model/MAML/MamlParameter.cs

@@ -9,6 +9,11 @@ public class MamlParameter : ICloneable
     {
         public SourceExtent Extent { get; set; }
 
+        /// <summary>
+        /// Additional options that determine how the section will be formated when rendering markdown.
+        /// </summary>
+        public SectionFormatOption FormatOption { get; set; }
+
         public string Type { get; set; }
 
         public string FullType { get; set; }

src/Markdown.MAML/Model/Markdown/HeadingNode.cs

@@ -9,10 +9,16 @@ public override MarkdownNodeType NodeType
 
         public int HeadingLevel { get; private set; }
 
-        public HeadingNode(string headingText, int headingLevel, SourceExtent sourceExtent) 
+        /// <summary>
+        /// Additional options that determine how the section will be formated when rendering markdown. This options will be passed on to MAML models when they are generated.
+        /// </summary>
+        public SectionFormatOption FormatOption { get; private set; }
+
+        public HeadingNode(string headingText, int headingLevel, SourceExtent sourceExtent, SectionFormatOption formatOption) 
             : base(headingText, sourceExtent)
         {
             this.HeadingLevel = headingLevel;
+            this.FormatOption = formatOption;
         }
     }
 }

src/Markdown.MAML/Model/Markdown/SectionBody.cs

@@ -0,0 +1,39 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Markdown.MAML.Model.Markdown
+{
+    /// <summary>
+    /// A section of text with formatting options.
+    /// </summary>
+    public sealed class SectionBody
+    {
+        public SectionBody(string text, SectionFormatOption formatOption)
+        {
+            Text = text;
+            FormatOption = formatOption;
+        }
+
+        public SectionBody(string text)
+            : this(text, SectionFormatOption.None)
+        { }
+
+        /// <summary>
+        /// The text of the section body.
+        /// </summary>
+        public string Text { get; private set; }
+
+        /// <summary>
+        /// Additional options that determine how the section will be formated when rendering markdown.
+        /// </summary>
+        public SectionFormatOption FormatOption { get; private set; }
+
+        public override string ToString()
+        {
+            return Text;
+        }
+    }
+}

src/Markdown.MAML/Model/Markdown/SectionFormatOption.cs

@@ -0,0 +1,22 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Markdown.MAML.Model.Markdown
+{
+    /// <summary>
+    /// Define options that determine how sections will be formated when rendering markdown.
+    /// </summary>
+    [Flags()]
+    public enum SectionFormatOption : byte
+    {
+        None = 0,
+
+        /// <summary>
+        /// A line break should be added after the section header.
+        /// </summary>
+        LineBreakAfterHeader = 1
+    }
+}

src/Markdown.MAML/Parser/MarkdownParser.cs

@@ -307,7 +307,10 @@ private void CreateHashHeader(Match regexMatch, SourceExtent sourceExtent)
                 new HeadingNode(
                     regexMatch.Groups[2].Value,
                     regexMatch.Groups[1].Value.Length,
-                    sourceExtent));
+                    sourceExtent,
+
+                    // Detect if a line break after the header exists. Mutiple line breaks will be reduced to one.
+                    (regexMatch.Groups[3].Captures.Count > 1) ? SectionFormatOption.LineBreakAfterHeader : SectionFormatOption.None));
         }
 
         private void CreateHashHeader2(Match regexMatch, SourceExtent sourceExtent)
@@ -318,7 +321,10 @@ private void CreateHashHeader2(Match regexMatch, SourceExtent sourceExtent)
                 new HeadingNode(
                     regexMatch.Groups[3].Value,
                     regexMatch.Groups[2].Value.Length,
-                    sourceExtent));
+                    sourceExtent,
+
+                    // Detect if a line break after the header exists. Mutiple line breaks will be reduced to one.
+                    (regexMatch.Groups[4].Captures.Count > 1) ? SectionFormatOption.LineBreakAfterHeader : SectionFormatOption.None));
         }
 
         private void CreateUnderlineHeader(Match regexMatch, SourceExtent sourceExtent)
@@ -333,7 +339,10 @@ private void CreateUnderlineHeader(Match regexMatch, SourceExtent sourceExtent)
                 new HeadingNode(
                     regexMatch.Groups[1].Value,
                     headerLevel,
-                    sourceExtent));
+                    sourceExtent,
+
+                    // Detect if a line break after the header exists. Mutiple line breaks will be reduced to one. 
+                    (regexMatch.Groups[3].Captures.Count > 1) ? SectionFormatOption.LineBreakAfterHeader : SectionFormatOption.None));
         }
 
         private void CreateTickCodeBlock(Match regexMatch, SourceExtent sourceExtent)