Publish group overview pages as the section index (index.md)

A <Group>/<Group>.md overview page is now emitted as <Group>/index.md so it renders as the group's landing page (with navigation.indexes) instead of a page nested under the group. Nested groups supported; other pages unchanged. Adds an Action-Test assertion. Addresses PSModule/Process-PSModule#371.

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -60,6 +60,23 @@ jobs:
           Name: PSModuleTest
           WorkingDirectory: tests/srcTestRepo
 
+      - name: Verify group overview pages publish as section index
+        shell: pwsh
+        run: |
+          $docs = 'tests/srcTestRepo/outputs/docs'
+          $expected = @('PSModule/index.md', 'SomethingElse/index.md')
+          $unexpected = @('PSModule/PSModule.md', 'SomethingElse/SomethingElse.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

@@ -231,6 +231,16 @@ $(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join
         Write-Host "   Path:     $file"
 
         $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder)
+
+        # A group overview page named after its folder (e.g. Auth/Auth.md) is published as the
+        # section landing page (Auth/index.md) so the navigation shows it when the group is
+        # selected, instead of listing it as a separate page nested under the group.
+        $parentFolderName = Split-Path -Path (Split-Path -Path $file.FullName -Parent) -Leaf
+        if ($file.BaseName -eq $parentFolderName) {
+            $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