Merge e348999 into dbb9bd4

CHANGELOG.md

@@ -1,5 +1,7 @@
-**v1.10** *In progress*
+**v1.10** *20240605*
 - Fixed issue with GH-33 where the `New-MDQuote` would output extra `> ` between quote lines
+- GH-28 Added new command `New-MDAlert` for GFM Alerts - thanks to @belibug
+- Updated tests from Pester v4 to v5
 
 **v1.9** *20200227*
 - Based on GH-20 the default output of `New-MDTable` has a cell length alignment per column. New parameter `-Shrink` is added to reduce the overall size and each cell is not padded. Thanks to @al-cheb

Demo/Demo.ps1

@@ -91,6 +91,22 @@ $lines=@(
 $markdown+=New-MDQuote -Lines $lines
 #endregion
 
+#region Github Flavoured Markdown Alerts
+$markdown+=New-MDHeader "Github Flavoured Markdown Alerts"
+$markdown+=New-MDParagraph -Lines "This is an important information"
+$lines=@(
+    "Alert is special callout style used in Github Flavoured Markdows"
+)
+$markdown+=New-MDAlert -Lines $lines -Style Important
+
+$markdown+=New-MDParagraph -Lines "Multi line Alert with 'Tip' Style"
+$lines=@(
+    "Git is "
+    "Line 2"
+)
+$markdown+=New-MDAlert -Lines $lines -Style Tip
+#endregion
+
 #region 
 $markdown+=New-MDHeader "Links"
 $markdown+="This is "+(New-MDLink -Text "an example" -Link "http://www.example.com/")+" inline link."

README.md

@@ -23,6 +23,7 @@ A powershell module to render markdown files.
 - New-MDList
 - New-MDParagraph
 - New-MDQuote
+- New-MDAlert
 - New-MDTable
 
 # Example script
@@ -123,6 +124,22 @@ $lines=@(
 $markdown+=New-MDQuote -Lines $lines
 #endregion
 
+#region Github Flavoured Markdown Alerts
+$markdown+=New-MDHeader "Github Flavoured Markdown Alerts"
+$markdown+=New-MDParagraph -Lines "This is an important information"
+$lines=@(
+    "Alert is special callout style used in Github Flavoured Markdows"
+)
+$markdown+=New-MDAlert -Lines $lines -Style Important
+
+$markdown+=New-MDParagraph -Lines "Multi line Alert with 'Tip' Style"
+$lines=@(
+    "Git is "
+    "Line 2"
+)
+$markdown+=New-MDAlert -Lines $lines -Style Tip
+#endregion
+
 #region 
 $markdown+=New-MDHeader "Links"
 $markdown+="This is "+(New-MDLink -Text "an example" -Link "http://www.example.com/")+" inline link."
@@ -234,6 +251,18 @@ $markdown
 > 
 > > Line 1
 > > Line 2
+>
+> # Github Flavoured Markdown Alerts
+> This is an important information
+> 
+> > [!IMPORTANT]
+> > Alert is special callout style used in Github Flavoured Markdows
+> 
+> Multi line Alert with 'Tip' Style
+> 
+> > [!TIP]
+> > Git is 
+> > Line 2
 > 
 > # Links
 > This is [an example](http://www.example.com/) inline link.

Src/Modules/MarkdownPS/Public/New-MDAlert.Tests.ps1

@@ -0,0 +1,43 @@
+BeforeAll {
+    . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
+    $MDQuoteFile = Join-Path -Path (Split-Path $PSCommandPath -Parent) -ChildPath 'New-MDQuote.ps1'
+    . $MDQuoteFile
+    $newLine = [System.Environment]::NewLine
+}
+Describe -Tag @('MarkdownPS', 'Cmdlet', 'Public') 'New-MDAlert' {
+    It '-Lines is null' {
+        { New-MDAlert -Lines $null } | Should -Throw '*because it is null.*'
+    }
+    It '-Lines is empty' {
+        { New-MDAlert -Lines @() } | Should -Throw '*because it is an empty array.*'
+    }
+    It '-Style out of range' {
+        { New-MDAlert -Lines 'Line 1' -Style Unknown } | Should -Throw -ErrorId 'ParameterArgumentValidationError,New-MDAlert'
+    }
+}
+Describe -Tag @('MarkdownPS', 'Cmdlet', 'Public', 'New-MDAlert') 'New-MDAlert' {
+    It '-Lines count is 1 & -Style not specified' {
+        $expected = '> [!NOTE]' + $newLine + '> Line 1' + $newLine + $newLine
+        New-MDAlert -Lines 'Line 1' | Should -Be $expected
+        New-MDAlert -Lines @('Line 1') | Should -Be $expected
+        'Line 1' | New-MDAlert | Should -Be $expected
+        @('Line 1') | New-MDAlert | Should -Be $expected
+    }
+    It '-Lines count is 2 & -Style not specified' {
+        $expected = '> [!NOTE]' + $newLine + '> Line 1' + $newLine + '> Line 2' + $newLine + $newLine
+        # New-MDAlert -Lines @('Line 1', 'Line 2') | Should -Be $expected
+        @('Line 1', 'Line 2') | New-MDAlert | Should -Be $expected
+    }
+    It '-Lines count is 1 & -Style provided' {
+        $expected = '> [!TIP]' + $newLine + '> Line 1' + $newLine + $newLine
+        New-MDAlert -Lines 'Line 1' -Style Tip | Should -Be $expected
+        New-MDAlert -Lines @('Line 1') -Style Tip | Should -Be $expected
+        'Line 1' | New-MDAlert -Style Tip | Should -Be $expected
+        @('Line 1') | New-MDAlert -Style Tip | Should -Be $expected
+    }
+    It '-Lines count is 2 & -Level provided' {
+        $expected = '> [!TIP]' + $newLine + '> Line 1' + $newLine + '> Line 2' + $newLine + $newLine
+        New-MDAlert -Lines @('Line 1', 'Line 2') -Style Tip | Should -Be $expected
+        @('Line 1', 'Line 2') | New-MDAlert -Style Tip | Should -Be $expected
+    }
+}

Src/Modules/MarkdownPS/Public/New-MDAlert.ps1

@@ -0,0 +1,96 @@
+<#
+    .SYNOPSIS
+        This commandlet output Github Flavoured Markdown alerts based on blockquote in markdown syntax
+
+    .DESCRIPTION
+        This cmdlet outputs a quote in markdown syntax which are Github Flavoured Markdown syntax, by adding `> [!STYLE]` as the first line, followed by the input lines each prefixed with `> ` on consecutive lines. 
+        Refer "https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts" for more details.
+
+    .PARAMETER  Lines
+        An array of lines to quote in markdown
+
+    .PARAMETER  Style
+        The Style of choice, options are one of (Tips, Warning, Note, Important, Caution), default style is Note
+
+    .PARAMETER NoNewLine
+        Controls if a new line is added at the end of the output
+
+    .EXAMPLE
+        New-MDAlert -Lines "Line 1"
+
+        > [!NOTE]
+        > Line 1
+
+    .EXAMPLE
+        New-MDAlert -Lines "Line 1" -Style Tip
+
+        > [!NOTE]
+        > Line 1
+
+        # Style accepts one of 4 value (Note, Tip, Important and Warning)        
+
+    .EXAMPLE
+        New-MDAlert -Lines @("Line 1","Line 2") -Style Important
+
+        > [!IMPORTANT]
+        > Line 1
+        > Line 2
+
+    .EXAMPLE
+        @("Line 1","Line 2") | New-MDAlert -Style Caution
+
+        >> [!CAUTION]
+        >> Line 1
+        >> Line 2
+
+    .LINK
+    Refer "https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts" for more details.
+
+    .INPUTS
+        An array of lines and choice of Style
+
+    .OUTPUTS
+        First line > [!STYLE] followed by each input line with a '> ' in the front 
+
+    .NOTES
+        Use the -NoNewLine parameter when you don't want the next markdown content to be separated.
+
+    .LINK
+        New-MDAlert
+        https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+#>
+function New-MDAlert {
+    [CmdletBinding()]
+    [OutputType([string])]
+    Param (
+        [Parameter(
+            Mandatory = $true,
+            Position = 0,
+            ValueFromPipeline = $true
+        )]
+        [string[]]$Lines,
+        [ValidateSet('Note', 'Tip', 'Important', 'Warning', 'CAUTION')]
+        [string]$Style = 'Note',
+        [ValidateNotNullOrEmpty()]
+        [switch]$NoNewLine = $false
+    )
+
+    Begin {
+        $output = ''
+        $admonition = '[!{0}]' -f $Style.ToUpper()
+        $output += New-MDQuote -Lines $admonition -Level 1 -NoNewLine
+    }
+
+    Process {
+        $lines | ForEach-Object {
+            $output += New-MDQuote -Lines $_ -Level 1 -NoNewLine
+        }
+    }
+
+    End {
+        if (-not $NoNewLine) {
+            $output += [System.Environment]::NewLine
+        }
+        $output
+    }
+}