🪲 [Fix]: Group overview pages now render as the section landing page

.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: <Group>/<Group>.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:

src/helpers/Build-PSModuleDocumentation.ps1

@@ -224,13 +224,42 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join
     }
 
     Write-Host '::group::Build docs - Move markdown files from public functions folder to docs output folder'
+    # Folders that already provide an explicit index page (any casing of index.md); a sibling
+    # <Group>.md in such a folder stays a normal page so it never overwrites the author-provided
+    # index page. Detected case-insensitively because the runner filesystem is case-sensitive.
+    $explicitIndexFolders = @(
+        Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -File |
+            Where-Object { $_.Name -ieq 'index.md' } |
+            ForEach-Object { $_.Directory.FullName } |
+            Sort-Object -Unique
+    )
     Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $file = $_
         $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 ($parentFolder -in $explicitIndexFolders) {
+                Write-Warning "Group overview page '$relPath' is not used as the section index because the folder already has an explicit index.md; publishing it as a normal page."
+            } 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

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`.