diff --git a/.github/workflows/Action-Test.yml b/.github/workflows/Action-Test.yml index ec94308..fa34cd0 100644 --- a/.github/workflows/Action-Test.yml +++ b/.github/workflows/Action-Test.yml @@ -60,6 +60,25 @@ jobs: Name: PSModuleTest WorkingDirectory: tests/srcTestRepo + - name: Verify group overview pages publish as section index + shell: pwsh + run: | + $docs = 'tests/srcTestRepo/outputs/docs' + # PSModule: /.md mapped to index.md. SomethingElse: explicit index.md + # passthrough. Widgets: Index.md normalized to index.md (case-insensitive). + $expected = @('PSModule/index.md', 'SomethingElse/index.md', 'Widgets/index.md') + $unexpected = @('PSModule/PSModule.md', 'SomethingElse/SomethingElse.md', 'Widgets/Index.md') + $failed = $false + foreach ($rel in $expected) { + if (Test-Path (Join-Path $docs $rel)) { Write-Host "OK present: $rel" } + else { Write-Host "ERR missing: $rel"; $failed = $true } + } + foreach ($rel in $unexpected) { + if (Test-Path (Join-Path $docs $rel)) { Write-Host "ERR should not exist: $rel"; $failed = $true } + else { Write-Host "OK absent: $rel" } + } + if ($failed) { throw 'Group overview pages were not published as section index (index.md).' } + - name: Lint documentation uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0 env: diff --git a/src/helpers/Build-PSModuleDocumentation.ps1 b/src/helpers/Build-PSModuleDocumentation.ps1 index e6387c7..5b8ab20 100644 --- a/src/helpers/Build-PSModuleDocumentation.ps1 +++ b/src/helpers/Build-PSModuleDocumentation.ps1 @@ -224,13 +224,48 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join } Write-Host '::group::Build docs - Move markdown files from public functions folder to docs output folder' - Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object { - $file = $_ + # Enumerate the public markdown once and reuse it (no second tree walk). + $publicMarkdownFiles = @(Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -File -Include '*.md') + + # Folders that provide an explicit index page. Detected case-insensitively because the runner + # filesystem is case-sensitive. Two index pages that differ only by case (index.md and + # Index.md) are ambiguous, so fail fast instead of silently overwriting one. + $explicitIndexFolders = [System.Collections.Generic.HashSet[string]]::new() + $indexGroups = $publicMarkdownFiles | Where-Object { $_.Name -ieq 'index.md' } | Group-Object { $_.Directory.FullName } + foreach ($group in $indexGroups) { + if ($group.Count -gt 1) { + $names = ($group.Group.Name | Sort-Object) -join ', ' + throw "Ambiguous section index in '$($group.Name)': multiple index pages ($names). Keep only one index.md." + } + [void]$explicitIndexFolders.Add($group.Name) + } + + foreach ($file in $publicMarkdownFiles) { $relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName) Write-Host " - $relPath" Write-Host " Path: $file" $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder) + + # A group's overview page becomes the section landing page (index.md) so the navigation + # shows it when the group is selected, instead of a page nested under the group. Authors + # can either name it after the folder (e.g. Auth/Auth.md) or provide Auth/index.md directly. + $parentFolder = Split-Path -Path $file.FullName -Parent + $parentFolderName = Split-Path -Path $parentFolder -Leaf + if ($file.Name -ieq 'index.md') { + # Normalize any casing (Index.md/INDEX.md) to index.md so it is treated as the + # section index on case-sensitive filesystems. + $docsFilePath = Join-Path -Path (Split-Path -Path $docsFilePath -Parent) -ChildPath 'index.md' + Write-Host ' Section index page detected - publishing as index.md' + } elseif ($file.BaseName -eq $parentFolderName) { + if ($explicitIndexFolders.Contains($parentFolder)) { + Write-Warning "Ignoring group overview '$relPath' as the section index; folder already has an explicit index.md." + } else { + $docsFilePath = Join-Path -Path (Split-Path -Path $docsFilePath -Parent) -ChildPath 'index.md' + Write-Host ' Group overview page detected - publishing as section index (index.md)' + } + } + Write-Host " MD path: $docsFilePath" $docsFolderPath = Split-Path -Path $docsFilePath -Parent $null = New-Item -Path $docsFolderPath -ItemType Directory -Force diff --git a/tests/srcTestRepo/src/functions/public/SomethingElse/SomethingElse.md b/tests/srcTestRepo/src/functions/public/SomethingElse/index.md similarity index 100% rename from tests/srcTestRepo/src/functions/public/SomethingElse/SomethingElse.md rename to tests/srcTestRepo/src/functions/public/SomethingElse/index.md diff --git a/tests/srcTestRepo/src/functions/public/Widgets/Index.md b/tests/srcTestRepo/src/functions/public/Widgets/Index.md new file mode 100644 index 0000000..f3eaf5b --- /dev/null +++ b/tests/srcTestRepo/src/functions/public/Widgets/Index.md @@ -0,0 +1,4 @@ +# Widgets + +This is the section overview for the Widgets group, authored as `Index.md` to verify +case-insensitive detection and normalization to `index.md`.