🪲 [Fix]: Example titles retain punctuation, numbering, and text

[Marius Storhaug (MariusStorhaug)]

Example titles now retain punctuation, numbering, and embedded Example N: text when you import help and generate Markdown, YAML, or MAML. Titled and untitled examples continue to work together without changes to your authoring workflow.

Fixed: Example titles no longer lose meaningful text

Trailing dashes and text that resembles an example heading are preserved instead of being removed during import.

Authored title text	Previously generated text	Corrected text
Title ending in -	Title ending in	Title ending in -
Compare Example 4: with Example 5	Compare with Example 5	Compare Example 4: with Example 5

Headings also retain their existing example numbers, including unbordered headings such as Example 9: An unbordered heading -. Localized headings, single examples, and mixed titled/untitled examples remain supported.

No migration or new parameters are required. Authoring .EXAMPLE <Title> requires a PowerShell version containing PowerShell/PowerShell#27387; this fix does not raise platyPS's minimum supported PowerShell version.

---

Technical details

Implementation

• TransformBase.GetExamples and TransformMaml.ReadExample share TransformUtils.GetExampleTitle.
• The helper removes whitespace-separated dashed borders without interpreting localized labels or deleting Example N: text. It replaces broad dash trimming and global string replacement.
• The existing model and Markdown, YAML, and MAML schemas are unchanged.
• Implementation progress: both import paths, cross-format regression coverage, and the exact upstream PR-runtime experiment are complete. The separate MAML reimport failure described below is outside this change.

Tests and results

The build completes with no warnings or errors. Repository tests use Pester 4.10.1. The exact upstream runtime is PowerShell/PowerShell#27387 at commit 74aba26f15d1ce18e5ff7eee99c4b8a60e604335 (PowerShell 7.7.0-preview.4).

Runtime	Test scope	Passed	Failed	Skipped	Pending
PowerShell 7.6.5	Eight related repository test files	459	0	8	1
Windows PowerShell 5.1	Same related repository test files	451	0	12	1
Exact upstream PR runtime	Complete example-title regression file	56	0	0	0
Exact upstream PR runtime	Original integration experiment, using rebuilt platyPS and Pester 5.8.0	42	1	0	0

Regression coverage exercises 17 title cases through live Get-Help, MAML import, and Markdown/YAML/MAML export. It includes punctuation, embedded example labels, numbering, localized labels, legacy variable-width borders, and unbordered titles. Four additional cases exercise real comment-based help, including a single line-comment example and mixed titled/untitled examples. These cases detect the upstream CommentHelpInfo.ExampleTitles capability rather than assuming a release version.

Before the fix, 36 of the original 52 regression tests failed. All 56 regression tests now pass on the supporting runtime. In the original sample-module experiment, all 10 example headings now survive exactly through Markdown, YAML, and MAML export, compared with 8/10 using published platyPS 1.0.3. All example code is retained.

Known, separate failure: reimporting platyPS-generated MAML containing empty example-remarks elements still raises an XmlException. This also occurs with published platyPS on stock PowerShell. It is the integration experiment's sole remaining failure; all title-preservation assertions pass. This PR does not change that parser behavior.

Standards and framework alignment

Changed surface	Standards checked	Framework docs checked	Result
src/Transform/*.cs	Existing C# transform conventions, shared helper reuse, model and runtime compatibility	None (no framework-specific docs)	Aligned
test/Pester/ExampleTitles.Tests.ps1	Repository Pester 4 conventions, public-command regression coverage, capability-based runtime gating	Repository README build and test guidance	Aligned

Issue scope is limited to #627 and PowerShell/PowerShell#27387. No additional issue closures are claimed.

---

This change is 

Relevant issues (or links)

Related work

• References 🚀 [Idea]: Support adding titles to examples #627
• References Comment-based help examples now support optional titles PowerShell#27387

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.