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

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)

src/Markdown.MAML/Renderer/MamlRenderer.cs

@@ -64,14 +64,14 @@ private static XElement CreateCommandElement(MamlCommand command)
                         new XElement(commandNS + "name", command.Name),
                         new XElement(commandNS + "verb", verb),
                         new XElement(commandNS + "noun", noun),
-                        new XElement(mamlNS + "description", GenerateParagraphs(command.Synopsis))),
-                    new XElement(mamlNS + "description", GenerateParagraphs(command.Description)),
+                        new XElement(mamlNS + "description", GenerateParagraphs(command.Synopsis?.Text))),
+                    new XElement(mamlNS + "description", GenerateParagraphs(command.Description?.Text)),
                     new XElement(commandNS + "syntax", command.Syntax.Select(syn => CreateSyntaxItem(syn, command))),
                     new XElement(commandNS + "parameters", command.Parameters.Select(param => CreateParameter(param))),
                     new XElement(commandNS + "inputTypes", command.Inputs.Select(input => CreateInput(input))),
                     new XElement(commandNS + "returnValues", command.Outputs.Select(output => CreateOutput(output))),
                     new XElement(mamlNS + "alertSet", 
-                        new XElement(mamlNS + "alert", GenerateParagraphs(command.Notes))),
+                        new XElement(mamlNS + "alert", GenerateParagraphs(command.Notes?.Text))),
                     new XElement(commandNS + "examples", command.Examples.Select(example => CreateExample(example))),
                     new XElement(commandNS + "relatedLinks", command.Links.Select(link => CreateLink(link))));
         }

src/Markdown.MAML/Renderer/Markdownv2Renderer.cs

@@ -114,7 +114,9 @@ private void AddCommand(MamlCommand command)
 
         private void AddLinks(MamlCommand command)
         {
-            AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.RELATED_LINKS);
+            var extraNewLine = command.Links != null && command.Links.Count > 0;
+
+            AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.RELATED_LINKS, extraNewLine);
             foreach (var link in command.Links)
             {
                 if (link.IsSimplifiedTextLink)
@@ -143,7 +145,7 @@ private void AddInputOutput(MamlInputOutput io)
                 return;
             }
 
-            var extraNewLine = string.IsNullOrEmpty(io.Description);
+            var extraNewLine = string.IsNullOrEmpty(io.Description) || ShouldBreak(io.FormatOption);
             AddHeader(ModelTransformerBase.INPUT_OUTPUT_TYPENAME_HEADING_LEVEL, io.TypeName, extraNewLine);
             AddParagraphs(io.Description);
         }
@@ -265,9 +267,18 @@ private string JoinWithComma(IEnumerable<string> args)
             return string.Join(", ", args);
         }
 
+        private bool ShouldBreak(SectionFormatOption formatOption)
+        {
+            // If the line break flag is set return true.
+            return formatOption.HasFlag(SectionFormatOption.LineBreakAfterHeader);
+        }
+
         private void AddParameter(MamlParameter parameter, MamlCommand command)
         {
-            AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, '-' + parameter.Name, extraNewLine: false);
+            var extraNewLine = ShouldBreak(parameter.FormatOption);
+
+            AddHeader(ModelTransformerBase.PARAMETERSET_NAME_HEADING_LEVEL, '-' + parameter.Name, extraNewLine: extraNewLine);
+
             // for some reason, in the update mode parameters produces extra newline.
             AddParagraphs(parameter.Description, this._mode == ParserMode.FormattingPreserve);
 
@@ -332,7 +343,10 @@ private void AddExamples(MamlCommand command)
             AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, MarkdownStrings.EXAMPLES);
             foreach (var example in command.Examples)
             {
-                AddHeader(ModelTransformerBase.EXAMPLE_HEADING_LEVEL, example.Title, extraNewLine: false);
+                var extraNewLine = ShouldBreak(example.FormatOption);
+
+                AddHeader(ModelTransformerBase.EXAMPLE_HEADING_LEVEL, example.Title, extraNewLine: extraNewLine);
+
                 if (!string.IsNullOrEmpty(example.Introduction))
                 {
                     AddParagraphs(example.Introduction);
@@ -432,17 +446,17 @@ private void AddSyntax(MamlCommand command)
             }
         }
 
-        private void AddEntryHeaderWithText(string header, string text)
+        private void AddEntryHeaderWithText(string header, SectionBody body)
         {
-            AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, header, extraNewLine: false);
+            var extraNewLine = body == null || string.IsNullOrEmpty(body.Text) || ShouldBreak(body.FormatOption);
+
+            // Add header
+            AddHeader(ModelTransformerBase.COMMAND_ENTRIES_HEADING_LEVEL, header, extraNewLine: extraNewLine);
+
             // to correctly handle empty text case, we are adding new-line here
-            if (string.IsNullOrEmpty(text))
-            {
-                _stringBuilder.Append(Environment.NewLine);
-            }
-            else
+            if (body != null && !string.IsNullOrEmpty(body.Text))
             {
-                AddParagraphs(text);
+                AddParagraphs(body.Text);
             }
         }
 
@@ -525,6 +539,12 @@ private void AddParagraphs(string body, bool noNewLines = false)
                 body = GetAutoWrappingForMarkdown(paragraphs.Select(para => GetEscapedMarkdownText(para.Trim())).ToArray());
             }
 
+            // The the body already ended in a line break don't add extra lines on to the end
+            if (body.EndsWith("\r\n\r\n"))
+            {
+                noNewLines = true;
+            }
+
             _stringBuilder.AppendFormat("{0}{1}{1}", body, noNewLines ? null : Environment.NewLine);
         }
 

src/Markdown.MAML/Renderer/YamlRenderer.cs

@@ -22,9 +22,9 @@ public static string MamlModelToString(MamlCommand mamlCommand)
             var model = new YamlCommand
             {
                 Name = mamlCommand.Name,
-                Notes = mamlCommand.Notes,
-                Remarks = mamlCommand.Description,
-                Summary = mamlCommand.Synopsis,
+                Notes = mamlCommand.Notes.Text,
+                Remarks = mamlCommand.Description.Text,
+                Summary = mamlCommand.Synopsis.Text,
                 Examples = mamlCommand.Examples.Select(CreateExample).ToList(),
                 Inputs = mamlCommand.Inputs.Select(CreateInputOutput).ToList(),
                 Links = mamlCommand.Links.Select(CreateLink).ToList(),