Publish group overview pages as the section index (index.md)#53
Open
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Open
Publish group overview pages as the section index (index.md)#53Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Conversation
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.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 11:41
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the documentation build pipeline so “group overview” markdown files (where the file basename matches its containing folder) are published as the section landing page (index.md), enabling navigation.indexes to link group headers to real content.
Changes:
- In
Build-PSModuleDocumentation.ps1, detect<Group>/<Group>.md(including nested groups) and publish it as<Group>/index.md. - In
Action-Test.yml, add a CI assertion that fixture group overviews publish asindex.mdand no longer as<Group>.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
src/helpers/Build-PSModuleDocumentation.ps1 |
Adds logic to remap folder-matching “group overview” pages to index.md in the docs output. |
.github/workflows/Action-Test.yml |
Adds a PowerShell validation step ensuring the new index.md publishing behavior is enforced in CI. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:00
View session
The section index can now be authored either as <Group>/<Group>.md (mapped to index.md) or as <Group>/index.md directly (published as-is). If a folder has both, the explicit index.md wins and the <Group>.md stays a normal page. Fixture: SomethingElse now uses index.md to cover the passthrough path (PSModule still covers the mapped path).
Marius Storhaug (MariusStorhaug)
force-pushed
the
fix/group-overview-index-page
branch
from
9769cd4 to
465e074
Compare
Comment on lines
+238
to
+242
| $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)' | ||
| } |
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 9, 2026 12:03
View session
Comment on lines
+229
to
+232
| $explicitIndexFolders = @( | ||
| Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Filter 'index.md' | | ||
| ForEach-Object { $_.Directory.FullName } | ||
| ) |
Comment on lines
+246
to
+251
| if ($file.Name -eq 'index.md') { | ||
| Write-Host ' Section index page (index.md) - publishing as-is' | ||
| } elseif ($file.BaseName -eq $parentFolderName -and $parentFolder -notin $explicitIndexFolders) { | ||
| $docsFilePath = Join-Path -Path (Split-Path -Path $docsFilePath -Parent) -ChildPath 'index.md' | ||
| Write-Host ' Group overview page detected - publishing as section index (index.md)' | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes a group overview page as the section index instead of a page nested under the group.
Problem
src/functions/public/<Group>/<Group>.mdwas copied tooutputs/docs/<Group>/<Group>.md, which renders as a page inside the group (e.g./Functions/PSModule/PSModule/) rather than the group's landing page. Withnavigation.indexesenabled in the site config, the section header had noindex.mdto link to, so clicking the group just expanded it.Change
In
Build-PSModuleDocumentation.ps1, the "Move markdown files from public functions folder to docs output folder" step now publishes a group overview page as the section index (<Group>/index.md). The overview can be authored two ways:<Group>/<Group>.md(basename matches the folder) — mapped to<Group>/index.md. Keeps the descriptive, folder-matching name used byTemplate-PSModule.<Group>/index.md— published as-is.If a folder somehow contains both, the explicit
index.mdwins and the<Group>.mdstays a normal page (no overwrite). Nested groups work (Auth/Context/Context.md→Auth/Context/index.md). Other hand-authored pages (e.g.PSModule/Notes.md) are unchanged.Result:
PSModule/PSModule.md→/Functions/PSModule/, shown when the group is selected.Test
Action-Test.ymlasserts the fixture group overviews publish asindex.md(PSModulevia the mapped<Group>.mdpath,SomethingElsevia the explicitindex.mdpath) and no longer as<Group>.md.Addresses PSModule/Process-PSModule#371 (issues are disabled on this repo, so tracked there).