Repository navigation
Update PlatyPS dependency from platyPS v0.14.x to Microsoft.PowerShell.PlatyPS v1.x #105
Description
Summary
The platyPS module (v0.14.2) used by PowerShellBuild is no longer supported. Microsoft has released a complete rewrite named Microsoft.PowerShell.PlatyPS v1.x, which is now the supported version. This issue tracks migrating all three platyPS-dependent public functions and updating the module dependency.
Reference: https://learn.microsoft.com/en-us/powershell/utility-modules/platyps/overview?view=ps-modules
Affected files
requirements.psd1— dependency declarationPowerShellBuild/Public/Build-PSBuildMarkdown.ps1PowerShellBuild/Public/Build-PSBuildMAMLHelp.ps1PowerShellBuild/Public/Build-PSBuildUpdatableHelp.ps1- Existing markdown docs under
docs/— must be migrated to the new schema
Cmdlet mapping
Old (platyPS v0.14.x) |
New (Microsoft.PowerShell.PlatyPS v1.x) |
|---|---|
New-MarkdownHelp |
New-MarkdownCommandHelp |
Update-MarkdownHelp |
Import-MarkdownCommandHelp | Export-MarkdownCommandHelp |
New-ExternalHelp |
Import-MarkdownCommandHelp | Export-MamlCommandHelp |
New-ExternalHelpCab |
Import-MarkdownCommandHelp | Export-MamlCommandHelp (cab via pipeline) |
Tasks
- Update
requirements.psd1to replaceplatyPS = '0.14.2'withMicrosoft.PowerShell.PlatyPS = '1.0.1' - Update
Build-PSBuildMarkdownto useNew-MarkdownCommandHelp/Import-MarkdownCommandHelp | Export-MarkdownCommandHelp - Update
Build-PSBuildMAMLHelpto useImport-MarkdownCommandHelp | Export-MamlCommandHelp - Update
Build-PSBuildUpdatableHelpto use the new cab pipeline - Migrate existing
docs/markdown files to the new schema usingMeasure-PlatyPSMarkdown | Import-MarkdownCommandHelp | Export-MarkdownCommandHelp - Update CI (
requirements.psd1/ GitHub Actions) to install the new module name - Verify
Get-Helpoutput is correct end-to-end after migration
Migration note for existing markdown
The new module ships Measure-PlatyPSMarkdown specifically to detect old-schema files and pipe them through the conversion:
$mdfiles = Measure-PlatyPSMarkdown -Path .\docs\en-US\*.md
$mdfiles | Where-Object Filetype -match 'CommandHelp' |
Import-MarkdownCommandHelp -Path { $_.FilePath } |
Export-MarkdownCommandHelp -OutputFolder .\docs\en-US -ForceRun this once as part of the migration to bring existing markdown into the new schema before updating the build functions.
Notes
- The new module is a full C# rewrite using
markdig(the same parser used by Microsoft Learn), so parsing is significantly more accurate and faster. - The new
CommandHelpobject model is pipeline-friendly — theImport-* | Export-*pattern replaces most single-step cmdlets from v0.14.x. platyPSv0.14.2 is still installable from the Gallery but receives no further fixes or updates.
Activity
fix: Address the review findings on the cabinet migration
tablackburn commentedon Aug 26, 2026
Done. All six sub-issues are closed and
mainis green at495b57e.Build-PSBuildMarkdownandBuild-PSBuildMAMLHelpBuild-PSBuildUpdatableHelp, closing #101 and #169Six mapped pull requests became three.
Where this issue's plan held, and where it did not
The cmdlet mapping above is right and was what made the migration tractable. Three things in
the plan turned out differently, and they are worth recording for anyone reading this later.
New-ExternalHelpCabdoes not map toExport-MamlCommandHelp. The table says "cab viapipeline"; the actual successor is
New-HelpCabinetFile, with a clean one-for-one parametermapping —
CabinetFilesFolder/MarkdownModuleFile/OutputFolderagainstCabFilesFolder/LandingPagePath/OutputFolder."Existing markdown docs under
docs/— must be migrated to the new schema" was a no-op here.This repository commits no command markdown;
docs/holds only the migration guide, and theper-command documents are generated at build time. #154 was re-scoped to the consumer-facing
version of that problem, which is real — and the answer turned out to be that the conversion is
automatic, because
Build-PSBuildMarkdownrunsUpdate-MarkdownCommandHelpover every existingdocument on each build. Consumers review a diff rather than run a one-shot.
requirements.psd1was updated, but PlatyPS is deliberately not inRequiredModules. Puttingit there failed 394 tests locally — the suite went 461 to 67. The two PlatyPS modules each ship
their own
YamlDotNetwith a different assembly identity, so aRequiredModulesentry forces theload into every session importing PowerShellBuild, including one already holding
platyPS0.14.2 —which is every consumer part-way through the upgrade. It is now an optional dependency, matching
how the docs tasks have always behaved.
alt3/Docusaurus.Powershelldoes declare it, and that iswhat broke maester365/maester#1955.
What the migration cost that nobody could have planned for
of the session. That is why
Build-PSBuildUpdatableHelphad to be stubbed in feat!: Migrate markdown and MAML help to Microsoft.PowerShell.PlatyPS 1.x #173 rather thanleft alone until PlatyPS 2d: migrate Build-PSBuildUpdatableHelp to the 1.x cab pipeline #152.
<ModuleName>with no opt-out(PowerShell/platyPS#835) and renames MAML to
-Help.xml. Both are flattened back so existing docs trees, site configuration, and.ExternalHelpdirectives keep working — the file name is pinned through front matter ratherthan renamed after export, which is the control point upstream actually uses.
Build-PSBuildUpdatableHelphad never worked at all — three independent defects, recorded inBuild-PSBuildUpdatableHelp cannot succeed: missing landing page, undefined $moduleOutDir, unbound Module #169. So PlatyPS 2d: migrate Build-PSBuildUpdatableHelp to the 1.x cab pipeline #152 was a port plus three fixes plus the task wiring, not a port.
platyPS#862 (a module landing page in an
export batch aborts the whole export and writes nothing) and
platyPS#863
(
Update-MarkdownCommandHelpfails on rerun when its own.bakexists).Consumer-facing outcome
Nine entries in
docs/migration-v0.8-to-v1.0.md,five of them from this chain: the module swap and its optional-dependency change, the removal of
$PSBPreference.Docs.AlphabeticParamsOrder, the 1.x schema, the new module landing page, updatablehelp now working and requiring a
HelpInfoUri, and the automatic conversion of a committeddocs/tree.
Phase 2 of #120 is complete, and #157 (
1.0.0-preview1) has no open blockers.