chore(docs): ✨ Update changelog and documentation for Overwrite parameter

* Clarified the behavior of the `$PSBPreference.Docs.Overwrite` parameter.
* Updated the default value from `$true` to `$false` in configuration files.
* Enhanced error handling in `Build-PSBuildMarkdown` function.

Author: HeyItsGilbert

CHANGELOG.md

@@ -11,9 +11,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - [**#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`.
+- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now
+  overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and
+  setting it to `$true`.
 
 ## [0.6.2] 2024-10-06
 

PowerShellBuild/Public/Build-PSBuildMarkdown.ps1

@@ -64,7 +64,13 @@ function Build-PSBuildMarkdown {
             Verbose = $VerbosePreference
             Force = $Overwrite
         }
+        if ($Overwrite) {
+            $newMDParams.Add('Force', $true)
+            $newMDParams.Remove('ErrorAction')
+        }
         New-MarkdownHelp @newMDParams > $null
+    } catch {
+        Write-Error "Failed to generate markdown help. : $_"
     } finally {
         Remove-Module $moduleName
     }

PowerShellBuild/build.properties.ps1

@@ -112,8 +112,8 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
         # 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
+        # Whether to overwrite existing markdown files and use comment based help as the source of truth
+        Overwrite = $false
     }
     Publish = @{
         # PowerShell repository name to publish modules to

README.md

@@ -119,7 +119,7 @@ match your environment.
 | $PSBPreference.Help.DefaultLocale                           | `(Get-UICulture).Name`                      | Default locale used for help generation                                                                                 |
 | $PSBPreference.Help.ConvertReadMeToAboutHelp                | `$false`                                    | Convert project readme into the module about file                                                                       |
 | $PSBPreference.Docs.RootDir                                 | `$projectRoot/docs`                         | Directory PlatyPS markdown documentation will be saved to                                                               |
-| $PSBPreference.Docs.Overwrite                               | `$true`                                     | Overwrite the markdown files in the docs folder using the comment based help as the source of truth.                    |
+| $PSBPreference.Docs.Overwrite                               | `$false`                                     | Overwrite the markdown files in the docs folder using the comment based help as the source of truth.                    |
 | $PSBPreference.Publish.PSRepository                         | `PSGallery`                                 | PowerShell repository name to publish                                                                                   |
 | $PSBPreference.Publish.PSRepositoryApiKey                   | `$env:PSGALLERY_API_KEY`                    | API key to authenticate to PowerShell repository with                                                                   |
 | $PSBPreference.Publish.PSRepositoryCredential               | `$null`                                     | Credential to authenticate to PowerShell repository with. Overrides `$psRepositoryApiKey` if defined                    |