New-MarkdownHelp returns error when generating markdown when document already exists

[fourpastmidnight]

Steps to reproduce

When running New-MarkdownHelp -Module 'MyModuleName' -OutputPath .\docs, I'm purposefully not using the -Force parameter. When doing so, I then get an error.

Expected behavior

Reading the documentation for New-MarkdownHelp:

SYNOPSIS

Creates help in markdown format.

EXAMPLES

Example 2: Create help from a module

PS C:\> Import-Module -Module "PlatyPS"
PS C:\> New-MarkdownHelp -Module "PlatyPS" -OutputFolder ".\docs" -Force


    Directory: D:\Working\PlatyPS\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:54 PM           1496 Get-HelpPreview.md
-a----        5/22/2016   6:54 PM           3208 Get-MarkdownMetadata.md
-a----        5/22/2016   6:54 PM           3059 New-ExternalHelp.md
-a----        5/22/2016   6:54 PM           2702 New-ExternalHelpCab.md
-a----        5/22/2016   6:54 PM           6234 New-MarkdownHelp.md
-a----        5/22/2016   6:54 PM           2346 Update-MarkdownHelp.md
-a----        5/22/2016   6:54 PM           1633 Update-MarkdownHelpModule.md
-a----        5/22/2016   6:54 PM           1630 Update-MarkdownHelpSchema.md

The first command loads the PlatyPS module into the current session by using the Import-Module cmdlet.

The second command creates help for all the cmdlets in the PlatyPS module. It stores them in the .\docs folder. This command specifies the Force parameter. Therefore, it overwrites existing help markdown files that have the same name.

Based on this documentation, I epxect that if I do not use the -Force parameter that help files would only be generated for those cmdlets in the module which already did not have a help document.

Actual behavior

Instead, I was presented with the following error:

Error: 2/1/2021 3:50:53 PM: 
At C:\<user-profile-path>\Documents\WindowsPowerShell\Modules\platyPS\0.14.1\platyPS.psm1:243 char:17 + ...             MySetContent -path (Join-Path $OutputFolder "$commandName ... +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [<<==>>] Exception: Cannot write to 'D:\src\git\<project-path>\docs\Get-ActionTemplateResource.md', file exists. Use -Force to overwrite.

Well, I specifically did not pass -Force because I don't want to overwrite the existing files. And I don't want to use Update-MarkdownHelp because it does bad things to existing files. (It changes the formatting of existing files in a way that I don't like; my files, while formatted slightly differently in some areas (e.g. common parameters is one), are still valid according to the schema defined by platyPS and generate help just fine using platyPS.) And that's unfortunate because I end up having to do the diff "manually" to update my help.

Environment data

0.14.1

[fourpastmidnight]

I suppose the resolution here could be one of two things:

1. Update platyPS to "just work" (i.e. work as expected)—skip the generation of markdown help when it already exists and create new documents for any cmdlets in the specified module where no such file exists.
2. Update the documentation for New-MarkdwonHelp to indicate that if a Markdown help file already exists for a given cmdlet in a module, that New-MarkdownHelp will fail unless -Force is specified, overwriting any existing help files.

[sdwheeler]

This is fixed in Microsoft.PowerShell.PlatyPS v1.