Feature: Add support for additional PlatyPS MarkdownHelp parameters (#77) (#78)

* Add `AlphabeticParamsOrder`, `ExcludeDontShow`, and `UseFullTypeName`
options to `$PSBPreference.Docs` with default value of `$false` in
`build.properties.ps1`

* Add the same three parameters to `Build-PSBuildMarkdown`

* Pass the same three parameters to `Build-PSBuildMarkdown` from
`IB.tasks.ps1` and `psakeFile.ps1`

* Add the same three parameters to the list of configurable options in
the readme file

Author: joshooaj

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.7.2] unreleased
+
+### Added
+
+- The `$PSBPreference` variable now supports the following PlatyPS `New-MarkdownHelp` and `Update-MarkdownHelp` boolean
+  options:
+  - `$PSBPreference.Docs.AlphabeticParamsOrder`
+  - `$PSBPreference.Docs.ExcludeDontShow`
+  - `$PSBPreference.Docs.UseFullTypeName`
+
 ## [0.7.1] 2025-04-01
 
 ### Fixes

PowerShellBuild/IB.tasks.ps1

@@ -117,11 +117,14 @@ $genMarkdownPreReqs = {
 # Synopsis: Generates PlatyPS markdown files from module help
 task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
     $buildMDParams = @{
-        ModulePath = $PSBPreference.Build.ModuleOutDir
-        ModuleName = $PSBPreference.General.ModuleName
-        DocsPath   = $PSBPreference.Docs.RootDir
-        Locale     = $PSBPreference.Help.DefaultLocale
-        Overwrite  = $PSBPreference.Docs.Overwrite
+        ModulePath            = $PSBPreference.Build.ModuleOutDir
+        ModuleName            = $PSBPreference.General.ModuleName
+        DocsPath              = $PSBPreference.Docs.RootDir
+        Locale                = $PSBPreference.Help.DefaultLocale
+        Overwrite             = $PSBPreference.Docs.Overwrite
+        AlphabeticParamsOrder = $PSBPreference.Docs.AlphabeticParamsOrder
+        ExcludeDontShow       = $PSBPreference.Docs.ExcludeDontShow
+        UseFullTypeName       = $PSBPreference.Docs.UseFullTypeName
     }
     Build-PSBuildMarkdown @buildMDParams
 }

PowerShellBuild/PowerShellBuild.psd1

@@ -1,6 +1,6 @@
 @{
     RootModule        = 'PowerShellBuild.psm1'
-    ModuleVersion     = '0.7.1'
+    ModuleVersion     = '0.7.2'
     GUID              = '15431eb8-be2d-4154-b8ad-4cb68a488e3d'
     Author            = 'Brandon Olin'
     CompanyName       = 'Community'

PowerShellBuild/Public/Build-PSBuildMarkdown.ps1

@@ -14,6 +14,12 @@ function Build-PSBuildMarkdown {
         The locale to save the markdown docs.
     .PARAMETER Overwrite
         Overwrite existing markdown files and use comment based help as the source of truth.
+    .PARAMETER AlphabeticParamsOrder
+        Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last.
+    .PARAMETER ExcludeDontShow
+        Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
+    .PARAMETER UseFullTypeName
+        Indicates that the target document will use a full type name instead of a short name for parameters.
     .EXAMPLE
         PS> Build-PSBuildMarkdown -ModulePath ./output/MyModule/0.1.0 -ModuleName MyModule -DocsPath ./docs -Locale en-US
 
@@ -34,7 +40,16 @@ function Build-PSBuildMarkdown {
         [string]$Locale,
 
         [parameter(Mandatory)]
-        [bool]$Overwrite
+        [bool]$Overwrite,
+
+        [parameter(Mandatory)]
+        [bool]$AlphabeticParamsOrder,
+
+        [parameter(Mandatory)]
+        [bool]$ExcludeDontShow,
+
+        [parameter(Mandatory)]
+        [bool]$UseFullTypeName
     )
 
     $moduleInfo = Import-Module "$ModulePath/$ModuleName.psd1" -Global -Force -PassThru
@@ -50,18 +65,27 @@ function Build-PSBuildMarkdown {
         }
 
         if (Get-ChildItem -LiteralPath $DocsPath -Filter *.md -Recurse) {
+            $updateMDParams = @{
+                AlphabeticParamsOrder = $AlphabeticParamsOrder
+                ExcludeDontShow       = $ExcludeDontShow
+                UseFullTypeName       = $UseFullTypeName
+                Verbose               = $VerbosePreference
+            }
             Get-ChildItem -LiteralPath $DocsPath -Directory | ForEach-Object {
-                Update-MarkdownHelp -Path $_.FullName -Verbose:$VerbosePreference > $null
+                Update-MarkdownHelp -Path $_.FullName @updateMDParams > $null
             }
         }
 
         # ErrorAction set to SilentlyContinue so this command will not overwrite an existing MD file.
         $newMDParams = @{
-            Module       = $ModuleName
-            Locale       = $Locale
-            OutputFolder = [IO.Path]::Combine($DocsPath, $Locale)
-            ErrorAction  = 'SilentlyContinue'
-            Verbose      = $VerbosePreference
+            Module                = $ModuleName
+            Locale                = $Locale
+            OutputFolder          = [IO.Path]::Combine($DocsPath, $Locale)
+            AlphabeticParamsOrder = $AlphabeticParamsOrder
+            ExcludeDontShow       = $ExcludeDontShow
+            UseFullTypeName       = $UseFullTypeName
+            ErrorAction           = 'SilentlyContinue'
+            Verbose               = $VerbosePreference
         }
         if ($Overwrite) {
             $newMDParams.Add('Force', $true)

PowerShellBuild/build.properties.ps1

@@ -115,6 +115,18 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
 
         # Whether to overwrite existing markdown files and use comment based help as the source of truth
         Overwrite = $false
+
+        # Whether to order parameters alphabetically by name in PARAMETERS section.
+        # Value passed to New-MarkdownHelp and Update-MarkdownHelp.
+        AlphabeticParamsOrder = $false
+
+        # Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
+        # Value passed to New-MarkdownHelp and Update-MarkdownHelp.
+        ExcludeDontShow = $false
+
+        # Indicates that the target document will use a full type name instead of a short name for parameters.
+        # Value passed to New-MarkdownHelp and Update-MarkdownHelp.
+        UseFullTypeName = $false
     }
     Publish = @{
         # PowerShell repository name to publish modules to

PowerShellBuild/psakeFile.ps1

@@ -124,11 +124,14 @@ $genMarkdownPreReqs = {
 }
 Task GenerateMarkdown -depends $PSBPreference.TaskDependencies.GenerateMarkdown -precondition $genMarkdownPreReqs {
     $buildMDParams = @{
-        ModulePath = $PSBPreference.Build.ModuleOutDir
-        ModuleName = $PSBPreference.General.ModuleName
-        DocsPath   = $PSBPreference.Docs.RootDir
-        Locale     = $PSBPreference.Help.DefaultLocale
-        Overwrite  = $PSBPreference.Docs.Overwrite
+        ModulePath            = $PSBPreference.Build.ModuleOutDir
+        ModuleName            = $PSBPreference.General.ModuleName
+        DocsPath              = $PSBPreference.Docs.RootDir
+        Locale                = $PSBPreference.Help.DefaultLocale
+        Overwrite             = $PSBPreference.Docs.Overwrite
+        AlphabeticParamsOrder = $PSBPreference.Docs.AlphabeticParamsOrder
+        ExcludeDontShow       = $PSBPreference.Docs.ExcludeDontShow
+        UseFullTypeName       = $PSBPreference.Docs.UseFullTypeName
     }
     Build-PSBuildMarkdown @buildMDParams
 } -description 'Generates PlatyPS markdown files from module help'

README.md

@@ -120,6 +120,9 @@ match your environment.
 | $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                               | `$false`                                    | Overwrite the markdown files in the docs folder using the comment based help as the source of truth.                    |
+| $PSBPreference.Docs.AlphabeticParamsOrder                   | `$false`                                    | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions: -Confirm, -WhatIf, -IncludeTotalCount, -Skip, and -First parameters will be the last. |
+| $PSBPreference.Docs.ExcludeDontShow                         | `$false`                                    | Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.                         |
+| $PSBPreference.Docs.UseFullTypeName                         | `$false`                                    | Indicates that the target document will use a full type name instead of a short name for parameters.                    |
 | $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                    |