diff --git a/CHANGELOG.md b/CHANGELOG.md index 93c4292..8d0e5b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ **v1.10** *In progress* - 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 **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 diff --git a/Demo/Demo.ps1 b/Demo/Demo.ps1 index 99a4217..d35df1e 100644 --- a/Demo/Demo.ps1 +++ b/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=@( + "Line 1" + "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." diff --git a/README.md b/README.md index 6d387e3..dba0081 100644 --- a/README.md +++ b/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=@( + "Line 1" + "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] +> > Line 1 +> > Line 2 > > # Links > This is [an example](http://www.example.com/) inline link. diff --git a/Src/Modules/MarkdownPS/Public/New-MDAlert.Tests.ps1 b/Src/Modules/MarkdownPS/Public/New-MDAlert.Tests.ps1 new file mode 100644 index 0000000..930e8e7 --- /dev/null +++ b/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 + } +} \ No newline at end of file diff --git a/Src/Modules/MarkdownPS/Public/New-MDAlert.ps1 b/Src/Modules/MarkdownPS/Public/New-MDAlert.ps1 new file mode 100644 index 0000000..a17c257 --- /dev/null +++ b/Src/Modules/MarkdownPS/Public/New-MDAlert.ps1 @@ -0,0 +1,95 @@ +<# + .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 = '' + $newLine = [System.Environment]::NewLine + $admonition = '> [!{0}]' -f $Style.ToUpper() + $output += $admonition + $newLine + } + + Process { + $output += New-MDQuote -Lines $Lines -Level 1 -NoNewLine + } + + End { + if (-not $NoNewLine) { + $output += $newLine + } + $output + } +} \ No newline at end of file diff --git a/Src/Modules/MarkdownPS/Public/New-MDQuote.ps1 b/Src/Modules/MarkdownPS/Public/New-MDQuote.ps1 index b7f7864..70c7992 100644 --- a/Src/Modules/MarkdownPS/Public/New-MDQuote.ps1 +++ b/Src/Modules/MarkdownPS/Public/New-MDQuote.ps1 @@ -81,10 +81,6 @@ function New-MDQuote { Process { $Lines|ForEach-Object { - # if($output -ne "") - # { - # $output+="$prefix"+[System.Environment]::NewLine - # } $output+="$prefix "+$_+[System.Environment]::NewLine } }