feat(markdown): ✨ Add Overwrite parameter to markdown generation

* Introduced an `Overwrite` parameter to control the overwriting of existing markdown files.
* Updated relevant functions and properties to utilize the new parameter.

Author: HeyItsGilbert

PowerShellBuild/IB.tasks.ps1

@@ -121,6 +121,7 @@ task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
         ModuleName = $PSBPreference.General.ModuleName
         DocsPath   = $PSBPreference.Docs.RootDir
         Locale     = $PSBPreference.Help.DefaultLocale
+        Overwrite  = $PSBPreference.Docs.Overwrite
     }
     Build-PSBuildMarkdown @buildMDParams
 }

PowerShellBuild/Public/Build-PSBuildMarkdown.ps1

@@ -29,7 +29,10 @@ function Build-PSBuildMarkdown {
         [string]$DocsPath,
 
         [parameter(Mandatory)]
-        [string]$Locale
+        [string]$Locale,
+
+        [parameter(Mandatory)]
+        [bool]$Overwrite
     )
 
     $moduleInfo = Import-Module "$ModulePath/$ModuleName.psd1" -Global -Force -PassThru
@@ -57,7 +60,7 @@ function Build-PSBuildMarkdown {
             OutputFolder   = [IO.Path]::Combine($DocsPath, $Locale)
             ErrorAction    = 'SilentlyContinue'
             Verbose        = $VerbosePreference
-            Force          = $true
+            Force          = $Overwrite
         }
         New-MarkdownHelp @newMDParams > $null
     } finally {

PowerShellBuild/build.properties.ps1

@@ -1,6 +1,6 @@
 BuildHelpers\Set-BuildEnvironment -Force
 
-$outDir        = [IO.Path]::Combine($env:BHProjectPath, 'Output')
+$outDir = [IO.Path]::Combine($env:BHProjectPath, 'Output')
 $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).ModuleVersion
 
 [ordered]@{
@@ -97,7 +97,7 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
             OutputFileFormat = 'JaCoCo'
         }
     }
-    Help  = @{
+    Help = @{
         # Path to updateable help CAB
         UpdatableHelpOutDir = [IO.Path]::Combine($outDir, 'UpdatableHelp')
 
@@ -111,6 +111,9 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
     Docs = @{
         # Directory PlatyPS markdown documentation will be saved to
         RootDir = [IO.Path]::Combine($env:BHProjectPath, 'docs')
+
+        # Overwrite existing markdown files and use comment based help as the source of truth
+        Overwrite = $true
     }
     Publish = @{
         # PowerShell repository name to publish modules to

PowerShellBuild/psakeFile.ps1

@@ -128,6 +128,7 @@ task GenerateMarkdown -depends StageFiles -precondition $genMarkdownPreReqs {
         ModuleName = $PSBPreference.General.ModuleName
         DocsPath   = $PSBPreference.Docs.RootDir
         Locale     = $PSBPreference.Help.DefaultLocale
+        Overwrite  = $PSBPreference.Docs.Overwrite
     }
     Build-PSBuildMarkdown @buildMDParams
 } -description 'Generates PlatyPS markdown files from module help'