build.ps1 'docs' task strips Jekyll frontmatter from regenerated cmdlet pages

[jagger]

Summary

Running Invoke-Build -File .\build.ps1 -Task docs -Configuration Debug regenerates all 259 function and 3 cmdlet doc pages under docs/commands/, but the regen strips the Jekyll title: / parent: / grand_parent: YAML frontmatter from every page. Without that frontmatter the pages fall out of the Just-the-Docs navigation tree on the GitHub Pages site.

Root cause appears to be the -NoMetadata flag on the New-MarkdownHelp call at build.ps1:142.

Impact

The docs task can't be used in its current state — running it produces a 263-file diff that, if committed, would break navigation across the entire Commands section. Maintainers have to fall back to hand-editing individual cmdlet pages whenever a parameter signature changes (e.g. the OtpCode Int32 → String change in v0.62.0, addressed by hand-edit in PR #452).

Suggested fixes

• Drop -NoMetadata and add a post-processing step that injects the Jekyll frontmatter based on the source file's directory (parent) and command name (title), or
• Keep -NoMetadata but have the regen step preserve existing frontmatter when it overwrites a file, or
• Use Update-MarkdownHelp (which currently only runs against cmdlets, not functions) for in-place updates that retain frontmatter — extending that branch to handle the function directories too.

Repro

Invoke-Build -File .\build.ps1 -Task docs -Configuration Debug
git status --short docs/commands/ | wc -l   # 263 files
git diff docs/commands/authentication/New-TssSession.md | head -6
# Shows the leading `---\ntitle: ...\nparent: ...\n---` block removed