📖 [Docs]: Module layout rules now cover the help URLs that grouping changes

[Marius Storhaug (MariusStorhaug)]

Module authors grouping functions by domain are now told up front that grouping changes each command's published documentation URL, and that every .LINK has to move with it. Previously the layout rules described only the source tree, so the URL change came as a CI failure rather than as guidance.

New: The canonical .LINK form is part of the layout rules

A public command's generated page is published under its group, so its canonical address is https://psmodule.io/<Module>/Functions/<Group>/<Name>/. The layout rules now state that form directly, note that each private helper links the public command it serves, and name PublicHelpLink as the check that enforces it — so a failing build is traceable back to the standard that describes it.

New: Regrouping an existing module calls out the link update

Moving a command into a group folder moves its generated page. Every .LINK in the module has to be updated in the same change, and any published reference to the old flat Functions/<Name>/ address stops resolving. The guidance now says to treat the link update and any redirect as part of the regrouping rather than as follow-up work.

---

Technical details

One file changed, src/docs/Modules/Standards.md: one bullet appended to the "Layout rules" list and one paragraph added after it. No existing rule is reworded and no heading changes, so inbound deep links still resolve.

This comes from a live failure. Regrouping PSModule/Yaml into domain folders followed the layout rules exactly and still failed CI on the first run:

[-] Should put the canonical documentation link first for Conversion/ConvertFrom-Yaml (ID: PublicHelpLink)
    Expected: 'https://psmodule.io/Yaml/Functions/Conversion/ConvertFrom-Yaml/'

Document-PSModule's Build-PSModuleDocumentation relocates each generated command page to mirror the source layout, so Functions/ConvertFrom-Yaml/ became Functions/Conversion/ConvertFrom-Yaml/. Ninety-eight .LINK values needed updating in that module — seven public commands plus ninety-one private helpers pointing at the public command they serve. The framework caught it, so nothing shipped wrong, but the cost is a wasted CI round trip on every module that regroups, scaling with the number of helpers.

The wording says "first .LINK" deliberately: the PublicHelpLink test checks the canonical link is first, and additional .LINK entries remain allowed.

The URL prefix is written as https://psmodule.io/<Module>/... to match the existing site, and the <Group>/<Name> placeholders match the <Group>.md convention already used in the surrounding rules.

Implementation plan progress: completes #104.

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Modules/Standards.md (prose)	PR Format — single unbroken paragraph lines	Document-PSModule page relocation; Test-PSModule PublicHelpLink	Aligned

Issue convergence sweep: scoped to open PSModule/docs issues about module layout and generated documentation. Only #104 is satisfied by this diff. PSModule/Yaml#53 is the delivery that surfaced it and is linked as context.

Relevant issues (or links)

• Closes Layout rules omit that domain grouping changes a command's canonical help URL #104
• 📖 [Docs]: YAML commands grouped by task with in-depth guides for each area Yaml#53

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter