Repository navigation
PlatyPS 2c: migrate Build-PSBuildMAMLHelp to Export-MamlCommandHelp #151
Description
Part of #120 (Phase 2 — PlatyPS migration, #105). Blocked by the markdown migration — MAML is generated from the markdown this chain produces, so the schema has to settle first.
Scope
Migrate PowerShellBuild/Public/Build-PSBuildMAMLHelp.ps1 from New-ExternalHelp to Import-MarkdownCommandHelp | Export-MamlCommandHelp.
Closes #100 (Build-PSBuildMAMLHelp tests) — written against the new API.
Watch for
- The new pipeline is two cmdlets where the old was one; error handling on a malformed markdown file needs to fail the build rather than silently emit partial MAML
- Verify the emitted MAML is loadable:
Get-Helpagainst the built module should return correct syntax, parameter, and example blocks — the 5.1 validation on [Tracking] PowerShellBuild v1.0.0 roadmap #120 confirmed the pipeline produces parseable MAML, but not that this repo's docs survive it
Done when
Build-PSBuildMAMLHelp uses only 1.x cmdlets, #100's tests cover it, Get-Help output is verified end-to-end, and any behavior change has a migration-guide entry.
Activity
tablackburn commentedon Aug 24, 2026
Route call settled 2026-08-24: #150 and #151 land as one pull request.
They are coupled by the markdown schema — migrating
Build-PSBuildMarkdownalone handsBuild-PSBuildMAMLHelpinput it cannot parse, and the two PlatyPS modules cannot be importedinto one session to bridge the gap. Splitting them produces a state that does not build.
That pull request also carries the dependency swap, since CI needs 1.x from this point onward:
requirements.psd1—platyPS = '0.14.2'→Microsoft.PowerShell.PlatyPS = '1.0.3'PowerShellBuild.psd1RequiredModules— theplatyPSentry. Consumer-facing andbreaking, so it needs an entry in
docs/migration-v0.8-to-v1.0.md.GenerateMarkdownandGenerateMAMLPreConditions inpsakeFile.ps1andIB.tasks.ps1Deliberately not included: the
GenerateUpdatableHelpPreCondition stays pointing atplatyPS, so that task skips with a warning rather than crashing on aNew-ExternalHelpCabthat is no longer installed.
Build-PSBuildUpdatableHelphas never worked (#169) and its testsare already skipped, so nothing observable regresses. #152 picks it up. Say so in the pull
request rather than leaving it to be discovered.
Baseline to regress against: #170 (#149), test-only, all CI legs green.
Rationale and the options that were rejected:
#120 (comment) and the PlatyPS
chain shape row on #120.
feat!: Migrate markdown and MAML help to Microsoft.PowerShell.PlatyPS…