Skip to content

Commit d4b270c

Browse files
📖 [Docs]: Module layout guidance now covers grouped help URLs (#453)
Module authors now see how grouping public commands changes their published help URLs and which links must move with the command. This keeps canonical links, private-helper references, and regrouping migrations aligned with the module layout. ## New: Grouped command help URL guidance The module-structuring guide now explains the canonical URL for a grouped public command, requires that URL to be the first public `.LINK`, and shows private helpers where to link. It also explains that moving a command changes its published path, so authors should update references in the same change and arrange redirects separately when existing links must continue to work. --- <details> <summary>Technical details</summary> - Changed surface: `docs/content/guides/structuring-your-module.md` (Markdown guidance). - Added the grouped URL form with the trailing slash, the first-link convention, private-helper link guidance, and regrouping migration implications. - Verified the URL pattern against `.github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1` and the documentation path handling in `.github/actions/Document-PSModule/src/helpers/Build-PSModuleDocumentation.ps1`. - Validation: `zensical build --strict` passed; the existing Pester 6.1.0 source-code suite passed all 13 tests with the grouped command fixtures. - Implementation plan progress: completes the documentation intent from PSModule/docs#105 and the scope of #485. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `docs/content/guides/structuring-your-module.md` | MSX Documentation Model, Markdown | Module source layout and canonical public help-link behavior | Aligned | Issue convergence sweep: scoped to open Process-PSModule issues concerning grouped module layout and canonical help links. #485 is fully satisfied by this change; #445 remains broader follow-up work because it concerns generating links during scaffolding/build. </details> <details> <summary>Relevant issues (or links)</summary> - Resolves #485 ### Related work - References PSModule/docs#105 - References #445 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 09fc45f commit d4b270c

1 file changed

Lines changed: 10 additions & 2 deletions

File tree

docs/content/guides/structuring-your-module.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ The goal is a stable repository anatomy so both humans and automation know exact
4040
│ ├── PSModule.yml # Settings parsed to drive matrices
4141
│ └── release.yml # Release automation template invoked on publish
4242
├── examples/ # Samples referenced in generated documentation
43-
│ └── General.ps1 # Example script ingested by Document-PSModule
43+
│ └── General.ps1 # Example script processed by Process-PSModule
4444
├── icon/ # Icon assets linked from manifest and documentation
4545
│ └── icon.png # Default module icon (PNG format)
4646
├── src/ # Module source, see "Module source code structure" below
@@ -67,6 +67,14 @@ Key expectations:
6767
- A group's overview page (`<Category>/<Category>.md` named after the folder, or `<Category>/index.md`) becomes that group's section landing page in the docs navigation.
6868
- The build step compiles `src/` into a root module file and removes the original project layout from the artifact.
6969
- Documentation generation mirrors the `src/functions/public` hierarchy so help content always aligns with source.
70+
- Put the canonical public help URL first in each public command's comment-based help. For a command at `src/functions/public/<Group>/<Name>.ps1`, use `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`. `Test-PSModule` enforces this as `PublicHelpLink`; additional `.LINK` entries may follow.
71+
- Point each private helper's `.LINK` entry to the public command it supports, using that command's canonical grouped URL.
72+
73+
### Grouping and published help URLs
74+
75+
Process-PSModule generates command help and publishes each page to mirror the relative path under `src/functions/public/`. Moving an existing command into a group therefore changes its published URL from `https://psmodule.io/<ModuleName>/Functions/<Name>/` to `https://psmodule.io/<ModuleName>/Functions/<Group>/<Name>/`.
76+
77+
When regrouping a command, update its first public `.LINK`, every private-helper `.LINK` that points to it, and any other references to the old URL in the same change. Process-PSModule does not create redirects for the old path; arrange a redirect separately in the publishing layer when existing links must continue to work.
7078

7179
## Module source code structure
7280

@@ -117,7 +125,7 @@ How the module is built.
117125
│ ├── finally.ps1 # Cleanup script appended to the root module
118126
│ ├── header.ps1 # Optional header injected at the top of the module
119127
│ ├── manifest.psd1 (optional) # Source manifest reused when present
120-
│ └── README.md # Module-level docs ingested by Document-PSModule
128+
│ └── README.md # Module-level docs processed by Process-PSModule
121129
```
122130

123131
### Declaring module dependencies

0 commit comments

Comments
 (0)