Merge pull request #18 from alt3/prettier

- various features and optimizations
- massive integration tests
- finalizes the refactoring

README.md

@@ -15,3 +15,15 @@ https://docusaurus-powershell.netlify.com
 ## Screenshot
 
 ![Screenshot](docusaurus/static/img/screenshot.png "Screenshot")
+
+## Who's Using This?
+
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td align="center"><a href="https://pester.dev/"><img src="https://raw.githubusercontent.com/pester/Pester/master/images/logo.png" width="100px;" alt=""/><br /><h3>Pester</h3></td>
+  </tr>
+</table>
+
+

Source/Private/InsertFinalNewline.ps1

@@ -0,0 +1,14 @@
+function InsertFinalNewline() {
+    <#
+        .SYNOPSIS
+            Adds a traling newline to the end of the file.
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content ($content + "`n")
+}

Source/Private/InsertPowershellMonikers.ps1

@@ -0,0 +1,25 @@
+function InsertPowershellMonikers() {
+    <#
+        .SYNOPSIS
+            Adds the `powershell` moniker to all code blocks without a language moniker.
+
+        .NOTES
+            We need to do this because PlatyPS does (yet) not add the moniker itself
+            => https://github.com/PowerShell/platyPS/issues/475
+
+        .LINK
+            https://regex101.com/r/Jpo9AL/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = '(```)\n((?:(?!```)[\s\S])+)(```)\n'
+
+    $content = [regex]::replace($content, $regex, '```powershell' + "`n" + '$2```' + "`n")
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/NewMarkdownExample.ps1

@@ -2,6 +2,9 @@ function NewMarkdownExample() {
     <#
         .SYNOPSIS
             Generates a new markdown example block.
+
+        .NOTES
+            Powershell language monicker inserted by the SetPowershellMoniker function.
     #>
     param(
         [Parameter(Mandatory = $True)][string]$Header,
@@ -10,7 +13,7 @@ function NewMarkdownExample() {
     )
 
     $example = "$Header`n"
-    $example += '```powershell' + "`n"
+    $example += '```' + "`n"
     $example += $Code
     $example += '```' + "`n"
 

Source/Private/ReadFile.ps1

@@ -0,0 +1,11 @@
+function ReadFile() {
+    <#
+        .SYNOPSIS
+            Retrieves raw markdown from file.
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    (Get-Content -Path $MarkdownFile.FullName -Raw).TrimEnd()
+}

Source/Private/ReplaceMarkdownExamples.ps1 → Source/Private/ReplaceExamples.ps1

@@ -1,4 +1,4 @@
-function ReplaceMarkdownExamples() {
+function ReplaceExamples() {
     <#
         .SYNOPSIS
             Replace PlatyPS generated code block examples.
@@ -16,14 +16,14 @@ function ReplaceMarkdownExamples() {
         [switch]$NoPlaceHolderExamples
     )
 
-    $content = (Get-Content -Path $MarkdownFile.FullName -Raw).TrimEnd()
+    $content = ReadFile -MarkdownFile $MarkdownFile
     [string]$newExamples = ""
 
     # ---------------------------------------------------------------------
     # extract all EXAMPLE nodes
-    # https://regex101.com/r/y4UxP8/2
+    # https://regex101.com/r/y4UxP8/7
     # ---------------------------------------------------------------------
-    $regexExtractExamples = [regex]::new('### (EXAMPLE|Example) [0-9][\s\S]*?(?=\n.*?#|$)')
+    $regexExtractExamples = [regex]'### (EXAMPLE|Example) [0-9][\s\S]*?(?=\n### EXAMPLE|\n## PARAMETERS|$)'
     $examples = $regexExtractExamples.Matches($content)
 
     if ($examples.Count -eq 0) {
@@ -137,7 +137,6 @@ function ReplaceMarkdownExamples() {
     $replacement = "## EXAMPLES`n`n$($newExamples)## PARAMETERS"
     $content = [regex]::replace($content, $regex, $replacement)
 
-    # replace file (UTF-8 without BOM)
-    $fileEncoding = New-Object System.Text.UTF8Encoding $False
-    [System.IO.File]::WriteAllLines($markdownFile.FullName, $content, $fileEncoding)
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
 }

Source/Private/SetMarkdownFrontMatter.ps1 → Source/Private/ReplaceFrontMatter.ps1

@@ -1,4 +1,4 @@
-function SetMarkdownFrontMatter() {
+function ReplaceFrontMatter() {
     <#
         .SYNOPSIS
             Replaces PlatyPS generated front matter with Docusaurus compatible front matter.
@@ -43,14 +43,14 @@ function SetMarkdownFrontMatter() {
 
     $newFrontMatter.Add("---") | Out-Null
 
-    # replace front matter
-    $content = (Get-Content -Path $MarkdownFile.FullName -Raw).TrimEnd()
+    # translate front matter to a string and replace CRLF with LF
+    $newFrontMatter = ($newFrontMatter| Out-String) -replace "`r`n", "`n"
 
+    # replace front matter
+    $content = ReadFile -MarkdownFile $MarkdownFile
     $regex = "(?sm)^(---)(.+)^(---).$\n"
+    $content = $content -replace $regex, $newFrontMatter
 
-    $newContent = $content -replace $regex, ($newFrontMatter | Out-String)
-
-    # replace file (UTF-8 without BOM)
-    $fileEncoding = New-Object System.Text.UTF8Encoding $False
-    [System.IO.File]::WriteAllLines($markdownFile.FullName, $newContent, $fileEncoding)
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
 }

Source/Private/ReplaceHeader1.ps1

@@ -0,0 +1,26 @@
+function ReplaceHeader1() {
+    <#
+        .SYNOPSIS
+            Removes the markdown H1 element OR preprends it with an extra newline if the -KeepHeader1 switch is used.
+
+        .LINK
+            https://regex101.com/r/hnVQvQ/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile,
+        [switch]$KeepHeader1
+    )
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = '(---)\n(# .+)'
+
+    if ($KeepHeader1) {
+        $content = $content -replace $regex, ("---`n`n" + '$2') # prepend newline (for first match only)
+    } else {
+        $content = $content -replace $regex, '---' # remove line (for first match only)
+    }
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/SeparateHeaders.ps1

@@ -0,0 +1,28 @@
+function SeparateHeaders() {
+    <#
+        .SYNOPSIS
+            Adds an empty line after markdown headers IF they are directly followed by an adjacent non-empty lines.
+
+        .NOTES
+            This ensures the markdown format will match with e.g. Prettier which in turn will
+            prevent getting format-change suggestions when running e.g. > Visual Studio Code
+            > CTRL+SHIFT+P > Format Document.
+
+        .LINK
+            https://regex101.com/r/Gsd3PX/1
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    Write-Verbose "Inserting empty line beneath non-separated headers."
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $regex = [regex]::new('(?m)([#+].+)\n(.+)')
+
+    $content = $content -replace $regex, ('$1' + "`n`n" + '$2')
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/SetLfLineEndings.ps1

@@ -0,0 +1,15 @@
+function SetLfLineEndings() {
+    <#
+        .SYNOPSIS
+            Replaces all CRLF line endings with LF so we can consitently use/expect `n when regexing etc.
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    $content = ($content -replace "`r`n", "`n") + "`n"
+
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/UnescapeSpecialChars.ps1

@@ -0,0 +1,22 @@
+function UnescapeSpecialChars() {
+    <#
+        .SYNOPSIS
+            Replaces platyPS escaped special chars with the un-escaped version.
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile
+    )
+
+    $content = ReadFile -MarkdownFile $MarkdownFile
+
+    # regular
+    $content = [regex]::replace($content, '\\`', '`') # backticks: `
+    $content = [regex]::replace($content, '\\\[', '[') # square opening brackets: [
+    $content = [regex]::replace($content, '\\\]', ']') # square closing brackets: ]
+
+    # specific cases
+    $content = [regex]::replace($content, '\\\\\\>', '\>') # as used in eg: PS C:\>
+
+    # replace file
+    WriteFile -MarkdownFile $MarkdownFile -Content $content
+}

Source/Private/WriteFile.ps1

@@ -0,0 +1,14 @@
+function WriteFile() {
+    <#
+        .SYNOPSIS
+            Writes content to a UTF-8 file without BOM using LF as newlines.
+    #>
+    param(
+        [Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile,
+        [Parameter(Mandatory = $True)][string]$Content
+    )
+
+    # replace file (UTF-8 without BOM)
+    $fileEncoding = New-Object System.Text.UTF8Encoding $False
+    [System.IO.File]::WriteAllText($MarkdownFile.FullName, $Content, $fileEncoding)
+}