Repository navigation
PlatyPS 2b: migrate Build-PSBuildMarkdown to New-MarkdownCommandHelp #150
Description
Part of #120 (Phase 2 — PlatyPS migration, #105). Blocked by #149.
Scope
Migrate PowerShellBuild/Public/Build-PSBuildMarkdown.ps1 from platyPS 0.14.x to Microsoft.PowerShell.PlatyPS 1.x.
| Old | New |
|---|---|
New-MarkdownHelp |
New-MarkdownCommandHelp |
Update-MarkdownHelp |
Import-MarkdownCommandHelp | Export-MarkdownCommandHelp |
Closes #99 (Build-PSBuildMarkdown tests) — written against the new API, so they land in this PR rather than being written twice.
Watch for
- Parameter surface drift between the old and new cmdlets — anything a consumer sets via
$PSBPreference.Docs.*that no longer has an equivalent is a breaking change and needs a migration-guide entry in this PR - Output shape and file naming: if generated markdown lands in different paths or with a different front-matter schema, consumers with committed
docs/will see churn
Done when
Build-PSBuildMarkdown uses only 1.x cmdlets, #99's tests cover it, CI is green on all legs, and any behavior change has an entry in docs/migration-v0.8-to-v1.0.md.
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…