Handles dashes in documentation in repository Wiki

CHANGELOG.md

@@ -5,9 +5,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+
+- Removed `build.psd1` as it is no longer required to build the project.
+
 ### Added
 
 - Added a devcontainer for development.
+- Added private function `ConvertTo-WikiSidebarLinkName` that converts a
+  name to a format suitable for use as a Wiki sidebar link.
+- New tasks:
+  - `Prepare_Markdown_FileNames_For_GitHub_Publish` - This task will prepare
+    the markdown file names for publishing to the GitHub Wiki by replacing
+    hyphens with spaces and converting Unicode hyphens to standard hyphens.
+    It can be controlled by parameter `ReplaceHyphen` in the task, which
+    defaults to `$true`.
+  - `Clean_WikiContent_For_GitHub_Publish` - This task will remove the top
+    level header from any markdown file where the top level header equals the
+    filename (converting Unicode hyphen to ASCII hyphen before comparison).
+    It can be controlled by parameter `RemoveTopLevelHeader` in the task, which
+    defaults to `$true`.
+
+### Changed
+
+- `New-GitHubWikiSidebar`
+  - Replaces ASCII hyphens for the Wiki sidebar.
+  - Replaces Unicode hyphens with standard hyphens for the Wiki sidebar.
+- Task `Generate_Wiki_Content`
+  - Now calls `Prepare_Markdown_FileNames_For_GitHub_Publish` after the
+    markdown files and external help file for command help has been generated.
+  - Now calls `Clean_WikiContent_For_GitHub_Publish` as the last step to
+    remove the top level header from any markdown file where the top level
+    header equals the filename.
+- Task `Generate_Markdown_For_Public_Commands`
+  - Verbose output of the markdown files that was created.
 
 ### Fixed
 

README.md

@@ -136,6 +136,29 @@ BuildWorkflow:
     - Publish_GitHub_Wiki_Content
 ```
 
+### `Clean_WikiContent_For_GitHub_Publish`
+
+This build task will clean the markdown files for publishing to the GitHub Wiki.
+It can be controlled by parameter `RemoveTopLevelHeader` in the task, which
+defaults to `$true`.
+
+Below is an example how the build task can be used when a repository is
+based on the [Sampler](https://github.com/gaelcolas/Sampler) project.
+
+```yaml
+BuildWorkflow:
+  '.':
+    - build
+
+  build:
+    - Clean
+    - Build_Module_ModuleBuilder
+    - Build_NestedModules_ModuleBuilder
+    - Create_changelog_release_output
+    - Generate_Markdown_For_Public_Commands
+    - Clean_WikiContent_For_GitHub_Publish
+```
+
 ### `Copy_Source_Wiki_Folder`
 
 This build task will copy the content of the wiki source folder if it exist
@@ -345,9 +368,11 @@ This is a metatask that runs the task (in order):
 - `Create_Wiki_Output_Folder`
 - `Generate_Markdown_For_Public_Commands`
 - `Generate_External_Help_File_For_Public_Commands`
+- `Prepare_Markdown_FileNames_For_GitHub_Publish`
 - `Clean_Markdown_Of_Public_Commands`
 - `Generate_Markdown_For_DSC_Resources`
 - `Copy_Source_Wiki_Folder`
+- `Clean_WikiContent_For_GitHub_Publish`
 
 Below is an example how the build task can be used when a repository is
 based on the [Sampler](https://github.com/gaelcolas/Sampler) project.
@@ -430,6 +455,29 @@ BuildWorkflow:
     - Publish_GitHub_Wiki_Content
 ```
 
+### `Prepare_Markdown_FileNames_For_GitHub_Publish`
+
+This build task will replace the hyphen in the markdown filenames with the
+unicode non-breaking hyphen. It can be controlled by parameter
+`ReplaceHyphen` in the task, which defaults to `$true`.
+
+Below is an example how the build task can be used when a repository is
+based on the [Sampler](https://github.com/gaelcolas/Sampler) project.
+
+```yaml
+BuildWorkflow:
+  '.':
+    - build
+
+  build:
+    - Clean
+    - Build_Module_ModuleBuilder
+    - Build_NestedModules_ModuleBuilder
+    - Create_changelog_release_output
+    - Generate_Markdown_For_Public_Commands
+    - Prepare_Markdown_FileNames_For_GitHub_Publish
+```
+
 ### `Publish_GitHub_Wiki_Content`
 
 This build task runs the command `Publish-WikiContent`. The task will only

source/Private/ConvertTo-WikiSidebarLinkName.ps1

@@ -0,0 +1,54 @@
+<#
+    .SYNOPSIS
+        Converts a name to a format suitable for use as a Wiki sidebar link.
+
+    .DESCRIPTION
+        The ConvertTo-WikiSidebarLinkName function takes a string input and converts
+        it to a format that is suitable for use as a link name in a Wiki sidebar. It
+        replaces hyphens with spaces and converts Unicode hyphens to standard hyphens.
+
+    .PARAMETER Name
+        The string to be converted. This parameter is mandatory and can be passed via
+        the pipeline.
+
+    .EXAMPLE
+        PS C:\> ConvertTo-WikiSidebarLinkName -Name "My-Page-Name"
+
+        Returns: "My Page Name"
+
+    .EXAMPLE
+        PS C:\> "Unicode‐Hyphen" | ConvertTo-WikiSidebarLinkName
+
+        Returns: "Unicode-Hyphen"
+
+    .INPUTS
+        System.String
+
+    .OUTPUTS
+        System.String
+
+    .NOTES
+        This function is used internally by the New-GitHubWikiSidebar function to
+        format link names in the generated sidebar.
+#>
+function ConvertTo-WikiSidebarLinkName
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
+        [System.String]
+        $Name
+    )
+
+    process
+    {
+        # Replace hyphens with spaces
+        $convertedName = $Name -replace '-', ' '
+
+        # Replace Unicode hyphen (U+2010) with a standard hyphen
+        $convertedName = $convertedName -replace [System.Char]::ConvertFromUtf32(0x2010), '-'
+
+        return $convertedName
+    }
+}

source/Public/New-GitHubWikiSidebar.ps1

@@ -169,7 +169,9 @@ Get-MarkdownMetadata -Path $($file.FullName) -ErrorAction 'Stop'
 
             foreach ($link in $sortedListItem)
             {
-                $null = $output.AppendLine('- [' + $link + '](' + $link + ')')
+                $linkName = ConvertTo-WikiSidebarLinkName -Name $link
+
+                $null = $output.AppendLine('- [' + $linkName + '](' + $link + ')')
             }
 
             $null = $output.AppendLine()
@@ -188,7 +190,9 @@ Get-MarkdownMetadata -Path $($file.FullName) -ErrorAction 'Stop'
 
         foreach ($link in $sidebarCategories.$category | Sort-Object)
         {
-            $null = $output.AppendLine('- [' + $link + '](' + $link + ')')
+            $linkName = ConvertTo-WikiSidebarLinkName -Name $link
+
+            $null = $output.AppendLine('- [' + $linkName + '](' + $link + ')')
         }
 
         $null = $output.AppendLine()

source/tasks/Clean_WikiContent_For_GitHub_Publish.build.ps1

@@ -0,0 +1,135 @@
+<#
+    .SYNOPSIS
+        This is a build task that modifies the wiki content to enhance the content
+        for use in GitHub repository Wikis.
+
+    .PARAMETER ProjectPath
+        The root path to the project. Defaults to $BuildRoot.
+
+    .PARAMETER OutputDirectory
+        The base directory of all output. Defaults to folder 'output' relative to
+        the $BuildRoot.
+
+    .PARAMETER BuiltModuleSubdirectory
+        Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName).
+        This is especially useful when you want to build DSC Resources, but you don't want the
+        `Get-DscResource` command to find several instances of the same DSC Resources because
+        of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`).
+
+        In most cases I would recommend against setting $BuiltModuleSubdirectory.
+
+    .PARAMETER VersionedOutputDirectory
+        Whether the Module is built with its versioned Subdirectory, as you would see it on a System.
+        For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/`
+
+    .PARAMETER ProjectName
+        The project name. Defaults to the empty string.
+
+    .PARAMETER SourcePath
+        The path to the source folder name. Defaults to the empty string.
+        The task does not use this parameter, see the notes below.
+
+    .PARAMETER DocOutputFolder
+        The path to the where the markdown documentation is written. Defaults to the
+        folder `./output/WikiContent`.
+
+    .PARAMETER BuildInfo
+        The build info object from ModuleBuilder. Defaults to an empty hashtable.
+
+    .NOTES
+        This is a build task that is primarily meant to be run by Invoke-Build but
+        wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler).
+
+        Parameter SourcePath is intentionally added to the task even if it is not used,
+        otherwise the tests fails. Most likely because the script Set-SamplerTaskVariable
+        expects the variable to always be available.
+#>
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules/Measure-ParameterBlockParameterAttribute', '', Justification = 'For boolean values when using (property $true $false) fails in conversion between string and boolean when environment variable is used if set as advanced parameter ([Parameter()])')]
+param
+(
+    [Parameter()]
+    [System.String]
+    $ProjectPath = (property ProjectPath $BuildRoot),
+
+    [Parameter()]
+    [System.String]
+    $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')),
+
+    [Parameter()]
+    [System.String]
+    $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
+
+    [Parameter()]
+    [System.Management.Automation.SwitchParameter]
+    $VersionedOutputDirectory = (property VersionedOutputDirectory $true),
+
+    [Parameter()]
+    [System.String]
+    $ProjectName = (property ProjectName ''),
+
+    [Parameter()]
+    [System.String]
+    $SourcePath = (property SourcePath ''),
+
+    [Parameter()]
+    [System.String]
+    $DocOutputFolder = (property DocOutputFolder 'WikiContent'),
+
+    [Parameter()]
+    [System.Management.Automation.SwitchParameter]
+    $RemoveTopLevelHeader = (property RemoveTopLevelHeader $true),
+
+    [Parameter()]
+    [System.Collections.Hashtable]
+    $BuildInfo = (property BuildInfo @{ })
+)
+
+# Synopsis: Modifies the wiki content to enhance the content for use in GitHub repository Wikis.
+Task Clean_WikiContent_For_GitHub_Publish {
+    # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables.
+    . Set-SamplerTaskVariable
+
+    $DocOutputFolder = Get-SamplerAbsolutePath -Path $DocOutputFolder -RelativeTo $OutputDirectory
+
+    "`tDocs output folder path = '$DocOutputFolder'"
+    ''
+
+    if ($RemoveTopLevelHeader)
+    {
+        $markdownFiles = Get-ChildItem -Path $DocOutputFolder -Filter '*.md'
+
+        Write-Build -Color 'Magenta' -Text 'Removing top level header from markdown files if it is the same as the filename.'
+
+        $markdownFiles |
+            ForEach-Object -Process {
+                $content = Get-Content -Path $_.FullName -Raw
+
+                $hasTopHeader = $content -match '(?m)^#\s+([^\r\n]+)'
+
+                $baseNameWithoutNonBreakingHyphen = $_.BaseName -replace [System.Char]::ConvertFromUtf32(0x2010), '-'
+
+                if ($hasTopHeader -and $Matches[1] -eq $baseNameWithoutNonBreakingHyphen)
+                {
+                    Write-Build -Color DarkGray -Text ('Top level header is the same as the filename. Removing top level header from: {0}' -f $_.Name)
+
+                    <#
+                        Remove only the top level header (# Header) and any empty lines
+                        following it. The regex should only target the first header found,
+                        without affecting later top level headers.
+                    #>
+                    $content = $content -replace '(?m)^#\s+(.*)\s*', ''
+
+                    # Save the updated content back to the file
+                    Set-Content -Path $_.FullName -Value $content
+                }
+                elseif ($hasTopHeader)
+                {
+                    Write-Build -Color DarkGray -Text ('Top level header is different from the filename. Skipping: {0}' -f $_.Name)
+                }
+                else
+                {
+                    Write-Build -Color DarkGray -Text ('No top level header found in: {0}' -f $_.Name)
+                }
+            }
+    }
+}

source/tasks/Generate_Markdown_For_Public_Commands.build.ps1

@@ -169,7 +169,7 @@ Import-Module -name '$DependentModule'
 
     $generateMarkdownScript += @"
 `n# Import the module that help is generate for
-`$importModule = Import-Module -Name '$ProjectName' -Passthru -ErrorAction 'Stop'
+`$importModule = Import-Module -Name '$ProjectName' -PassThru -ErrorAction 'Stop'
 
 if (-not `$importModule)
 {
@@ -212,14 +212,20 @@ New-MarkdownHelp @newMarkdownHelpParams
         The scriptblock is run in a separate process to avoid conflicts with
         other modules that are loaded in the current process.
     #>
-    & $pwshPath -Command $generateMarkdownScriptBlock -ExecutionPolicy 'ByPass' -NoProfile
+    $markdownFiles = & $pwshPath -Command $generateMarkdownScriptBlock -ExecutionPolicy 'ByPass' -NoProfile
+
+    Write-Build -Color DarkGray -Text "Generated markdown files:"
+
+    $markdownFiles | ForEach-Object -Process {
+        Write-Build -Color DarkGray -Text ("`t{0}" -f $_.FullName)
+    }
 
     if (-not $?)
     {
         throw "Failed to generate markdown documentation for the public commands for module '$ProjectName'."
     }
     else
     {
-        Write-Build -Color 'Green' -Text 'Markdown for command documentation created for module '$ProjectName'.'
+        Write-Build -Color Green -Text 'Markdown for command documentation created for module '$ProjectName'.'
     }
 }

source/tasks/Generate_Wiki_Content.build.ps1

@@ -84,4 +84,4 @@
     $BuildInfo = (property BuildInfo @{ })
 )
 
-Task Generate_Wiki_Content Create_Wiki_Output_Folder, Generate_Markdown_For_Public_Commands, Generate_External_Help_File_For_Public_Commands, Clean_Markdown_Of_Public_Commands, Generate_Markdown_For_DSC_Resources, Copy_Source_Wiki_Folder
+Task Generate_Wiki_Content Create_Wiki_Output_Folder, Generate_Markdown_For_Public_Commands, Generate_External_Help_File_For_Public_Commands, Prepare_Markdown_FileNames_For_GitHub_Publish, Clean_Markdown_Of_Public_Commands, Generate_Markdown_For_DSC_Resources, Copy_Source_Wiki_Folder, Clean_WikiContent_For_GitHub_Publish