Update Build-PSBuildMarkdown.ps1

.markdownlint.json

@@ -2,5 +2,9 @@
   "$schema": "https://raw.githubusercontent.com/DavidAnson/vscode-markdownlint/refs/heads/main/markdownlint-config-schema.json",
   "MD024": {
     "siblings_only": true
+  },
+  "MD013": {
+    "code_blocks": false,
+    "tables": false
   }
 }

CHANGELOG.md

@@ -7,9 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Breaking Changes
+
 - [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules
   are now explicitly created as UTF-8 files.
-
+- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) Overwrite existing
+  markdown files and use the comment based help as the source of truth. This can
+  be disabled if `$PSBPreference.Docs.Overwrite` is set to `$false`.
 
 ## [0.6.2] 2024-10-06
 

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,6 +60,7 @@ function Build-PSBuildMarkdown {
             OutputFolder   = [IO.Path]::Combine($DocsPath, $Locale)
             ErrorAction    = 'SilentlyContinue'
             Verbose        = $VerbosePreference
+            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'