🪲 [Fix]: Group overview pages now render as the section landing page by MariusStorhaug · Pull Request #53 · PSModule/Document-PSModule

Marius Storhaug (MariusStorhaug) · 2026-07-09T11:41:11Z

When a command group has an overview page, it now becomes the landing page for that group in the generated documentation — the content shown when the group is selected in the navigation. Previously the overview was published as a separate page nested under the group (for example .../Functions/Auth/Auth/), so selecting the group only expanded it and the overview was easy to miss.

Addresses Publish group overview pages as the section index instead of a nested sub-page Process-PSModule#371

Fixed: Group overview pages are the section landing page

Give a command group an overview page and it now renders as that group's index on the docs site (/Functions/<Group>/). You can author it either way:

src/functions/public/<Group>/<Group>.md — named after the folder (the convention Template-PSModule ships). It is published as the group's index.md.
src/functions/public/<Group>/index.md — published as-is.

For example, src/functions/public/Auth/Auth.md (or Auth/index.md) now serves the Auth group's landing page at /Functions/Auth/ instead of /Functions/Auth/Auth/.

Existing modules that already use the <Group>/<Group>.md convention (such as Template-PSModule and the GitHub module's Auth group) get the corrected behavior automatically — no source changes required. Nested groups work too (Auth/Context/Context.md → /Functions/Auth/Context/), and other hand-authored pages (e.g. PSModule/Notes.md) continue to publish as regular pages. If a folder somehow contains both a <Group>.md and an index.md, the explicit index.md is kept.

Technical Details

src/helpers/Build-PSModuleDocumentation.ps1 — in the "Move markdown files from public functions folder to docs output folder" step, a group overview whose basename matches its parent folder is written to <Group>/index.md; an existing index.md is published unchanged. Folders that already contain an index.md are collected before the move loop, so a sibling <Group>.md is never moved over an author-provided index.md (order-independent).
.github/workflows/Action-Test.yml — added a step asserting the fixture group overviews publish as index.md (PSModule via the folder-name path, SomethingElse via the explicit index.md path) and no longer as <Group>.md.
tests/srcTestRepo/src/functions/public/SomethingElse/SomethingElse.md renamed to index.md to cover the explicit-index.md path.
Relies on navigation.indexes, already enabled in the module mkdocs.yml template, for the section header to link to the index page.

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

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 as index.md and 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.

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

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

…arn on collision Detect explicit index pages case-insensitively (Where-Object -ieq) with de-duplication for case-sensitive runners; normalize any casing of index.md (Index.md/INDEX.md) to index.md in the output so MkDocs treats it as the section index; and emit a warning (instead of a silent overwrite) when a <Group>.md and an index.md coexist. Adds a Widgets/Index.md fixture to cover the casing path on Linux.

Copilot

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

Shorten the Write-Warning message to a single line under the 150-char PSScriptAnalyzer limit configured in .github/linters/.powershell-psscriptanalyzer.psd1.

Copilot

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Enumerate public markdown once and derive the explicit-index folder set from it (no second tree walk). Group index pages per folder and throw a clear error when a folder has two that differ only by case (index.md + Index.md), instead of letting Move-Item -Force silently overwrite one. Addresses the remaining Copilot review comment.

Copilot

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings July 9, 2026 11:41

Marius Storhaug (MariusStorhaug) added the Patch label Jul 9, 2026

Copilot started reviewing on behalf of Marius Storhaug (MariusStorhaug) July 9, 2026 11:41 View session