Generate a Functions landing page that indexes all commands grouped by section

[MariusStorhaug]

A module consumer opens the published documentation site and selects the top-level Functions section to discover what commands the module provides. After #371, selecting a command group shows that group's landing page, but selecting Functions itself only expands the navigation — there is no single page that presents the module's full command surface at a glance. To learn what a module offers, the reader has to click into each group one by one.

Note

The component that generates the documentation lives in PSModule/Document-PSModule (src/helpers/Build-PSModuleDocumentation.ps1). Issues are disabled on that repository, so this work is tracked here in Process-PSModule.

Request

Desired capability

The Functions section should have a landing page that indexes every command the module exports, organized into sections that mirror the command-group folders under src/functions/public. For each group:

• The section heading is the group's title (the sub-folder name).
• When the group provides an overview/index page whose front matter contains a description, that description is rendered as a short, synopsis-style paragraph beneath the heading.
• When the group has no index page (or the index page has no description), no description is rendered — the heading and table are shown on their own.
• A table lists the group's commands, each linked to its command page, so the whole surface area is scannable from one place.

Current experience

Selecting Functions in the navigation expands it into per-group section pages, but the Functions section has no landing content of its own. Discovering all commands requires visiting each group individually; there is no consolidated index.

Desired experience

Selecting Functions shows an index page: one section per command group, each with an optional short description and a table of that group's commands.

Illustrative output

# Functions

## Auth

Commands for authenticating against the service and managing the current context.

| Command | Synopsis |
| --- | --- |
| [Connect-Service](Auth/Connect-Service.md) | Establishes an authenticated session. |
| [Disconnect-Service](Auth/Disconnect-Service.md) | Ends the current session. |

## Repository

| Command | Synopsis |
| --- | --- |
| [Get-Repository](Repository/Get-Repository.md) | Gets one or more repositories. |
| [New-Repository](Repository/New-Repository.md) | Creates a repository. |

In the example, Auth has an overview page with a front-matter description, so a paragraph is shown; Repository has no index page, so the description is skipped.

Acceptance criteria

• The Functions section has a landing page (its index) that lists every exported command.
• Commands are grouped into sections matching the command-group folders; each section heading is the group (sub-folder) name.
• When a group has an index page with a description in its front matter, that description is rendered as a short paragraph under the section heading.
• When a group has no index page, or its index page has no description, no description is rendered for that section.
• Each section contains a table of the group's commands, each linked to its command page.
• Every exported command appears in exactly one section table.
• The page is generated automatically with no per-module source or configuration changes.
• Nested command groups are represented consistently.

---

Technical decisions

Component placement. The change is made in PSModule/Document-PSModule (src/helpers/Build-PSModuleDocumentation.ps1), consistent with #371. That helper already imports the built module, enumerates the exported commands, restructures the generated markdown to mirror src/functions/public, and produces each group's section index (index.md). Generating the aggregated Functions index is a natural extension of the same helper, where both the command metadata and the section index pages are already available.

Where the page lands. The helper writes the aggregated index to outputs/docs/index.md (the root of the generated functions docs tree). The Process-PSModule Build-Site step copies outputs/docs/* into outputs/site/docs/Functions/, so the file is published as Functions/index.md.

No site-config change required. The module MkDocs Material configuration has no explicit nav: (navigation is derived from the folder tree) and enables navigation.indexes. A Functions/index.md is therefore picked up automatically as the Functions section landing page — the same mechanism #371 relies on. Only the generation step needs to change.

Section model. One section per command-group folder under src/functions/public. The section heading is the group (sub-folder) name. Nested command groups are rendered as nested subsections, with heading depth following folder depth, so the index mirrors the navigation hierarchy.

Section description source. The description is read from the group's section index page front matter — the index.md produced by #371 (either an author-provided index.md or a <Group>/<Group>.md overview renamed to index.md). A dedicated front-matter field (for example description) holds the synopsis-style text. If the group has no index page, or the field is absent/empty, the description is omitted. Overview pages currently carry no front matter, so authors opt in by adding the field — no existing page changes behavior until it does.

Table content. Each section table has two columns: the command name (linked to its command page via a relative path such as <Group>/<Command>.md) and the command's synopsis. The synopsis is sourced from the command's help (available from the imported module and the generated per-command markdown).

Ordering. Groups and commands are ordered deterministically (alphabetically) so the generated page is stable across builds.

Timing. The index is built at the end of Build-PSModuleDocumentation, after the restructure/move step, when the section index.md files and per-command pages exist and the module is imported (command metadata is available).

Zensical migration. The documentation pipeline is being migrated to Zensical (#335 / #336 / #337). The aggregated Functions index should be preserved as part of that migration so capability parity is maintained.

Test strategy. Extend the Process-PSModule documentation fixtures (tests/srcTestRepo, tests/srcWithManifestTestRepo) with a group that has an index page carrying a front-matter description and a group that has none, then assert the generated Functions index contains the expected sections, tables, links, and conditional descriptions.

---

Implementation plan

Core change (Document-PSModule)

• In src/helpers/Build-PSModuleDocumentation.ps1, after the "Move markdown files from public functions folder to docs output folder" step, enumerate the command-group folders in the docs output tree.
• For each group, resolve the section heading from the group (sub-folder) name and render nested groups as nested subsections following folder depth.
• Read the group's index.md front matter and capture the description field when present; omit the description when the group has no index.md or no description.
• Build a per-group table of commands with a linked command name and the command's synopsis, ordered deterministically.
• Write the aggregated page to outputs/docs/index.md so Build-Site publishes it as Functions/index.md.

Verification / tests (Process-PSModule)

• Add a fixture group with an index page that has a front-matter description; assert the description renders under its heading.
• Add a fixture group without an index page; assert no description is rendered but the table is present.
• Assert every exported command appears in exactly one section table and links to its command page.
• Confirm the generated page publishes as Functions/index.md and renders as the Functions section landing page.
• Confirm no mkdocs.yml / navigation changes are required.

Documentation

• Document the Functions index behavior and the front-matter description convention for group index pages (for example in Template-PSModule and the framework documentation).

Related

• Builds on #371 (publish group overview pages as the section index).
• Should be carried into the Zensical migration (#335, #336, #337).