PowerShell · Marius Storhaug (MariusStorhaug) · Feb 26, 2026 · Feb 26, 2026 · Apr 17, 2026 · May 1, 2026
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text;
 
@@ -423,7 +424,13 @@ public static string GetHelpComments(PSObject help)
             }
 
             PSObject examples = GetProperty<PSObject>(help, "examples");
-            PSObject[] example = GetProperty<PSObject[]>(examples, "example");
+            // Get-Help returns a single example as PSObject and multiple as PSObject[].
+            // Normalize both to IEnumerable<PSObject> so the loop handles either case.
+            PSObject[] exampleArray = GetProperty<PSObject[]>(examples, "example");
+            IEnumerable<PSObject> example = exampleArray
+                ?? (GetProperty<PSObject>(examples, "example") is PSObject singleEx
+                    ? new[] { singleEx }
+                    : null);
             if (example != null)
             {
                 foreach (PSObject ex in example)
@@ -461,7 +468,20 @@ public static string GetHelpComments(PSObject help)
 
                     if (exsb.Length > 0)
                     {
-                        sb.Append("\n\n.EXAMPLE\n\n");
+                        // The title property value may be stored as a PSObject wrapping a string,
+                        // so use ToString() on the raw Value rather than 'Value as string'.
+                        ReadOnlySpan<char> exampleTitle = ExtractExampleTitle(ex.Properties["title"]?.Value?.ToString());
+                        if (!exampleTitle.IsEmpty)
+                        {
+                            sb.Append("\n\n.EXAMPLE ");
+                            sb.Append(exampleTitle);
+                            sb.Append("\n\n");
+                        }
+                        else
+                        {
+                            sb.Append("\n\n.EXAMPLE\n\n");
+                        }
+
                         sb.Append(exsb);
                     }
                 }
@@ -498,6 +518,22 @@ public static string GetHelpComments(PSObject help)
             return sb.ToString();
         }
 
+        /// <summary>
+        /// Extracts the title after the first ": " delimiter in a generated Get-Help example heading.
+        /// The final dash border and surrounding whitespace are trimmed, preserving authored dashes
+        /// separated from the border by a space. The localized example label is not interpreted,
+        /// and a heading without the delimiter has no title.
+        /// </summary>
+        private static ReadOnlySpan<char> ExtractExampleTitle(string decoratedTitle)
+        {
+            ReadOnlySpan<char> heading = decoratedTitle.AsSpan();
+            int separatorIndex = heading.IndexOf(": ", StringComparison.Ordinal);
+
+            return separatorIndex < 0 || separatorIndex + 2 >= heading.Length
+                ? default
+                : heading.Slice(separatorIndex + 2).TrimEnd('-').Trim();
+        }
+
         #endregion
     }
 }
@@ -10687,6 +10687,16 @@ public sealed class CommentHelpInfo
         /// </summary>
         public ReadOnlyCollection<string> Examples { get; internal set; }
 
+        /// <summary>
+        /// The optional titles of each .EXAMPLE section, parallel to <see cref="Examples"/>.
+        /// Each entry corresponds to the example body at the same index. An entry is an empty
+        /// string when the example was declared without a title (the historical form
+        /// <c>.EXAMPLE</c> on its own line). When the inline form
+        /// <c>.EXAMPLE &lt;Title&gt;</c> is used, the trimmed title text is stored at the
+        /// matching index.
+        /// </summary>
+        public ReadOnlyCollection<string> ExampleTitles { get; internal set; }
+
         /// <summary>
         /// The help content from all of the specified .INPUT sections.
         /// </summary>
@@ -10782,9 +10792,21 @@ public string GetCommentBlock()
 
             for (int index = 0; index < Examples.Count; index++)
             {
-                var example = Examples[index];
-                sb.AppendLine(".EXAMPLE");
-                sb.AppendLine(example);
+                // ExampleTitles is always parallel to Examples, so the index is valid whenever
+                // Examples[index] is. An empty entry means the example was declared untitled.
+                string title = ExampleTitles[index];
+
+                if (!string.IsNullOrEmpty(title))
+                {
+                    sb.Append(".EXAMPLE ");
+                    sb.AppendLine(title);
+                }
+                else
+                {
+                    sb.AppendLine(".EXAMPLE");
+                }
+
+                sb.AppendLine(Examples[index]);
             }
 
             for (int index = 0; index < Links.Count; index++)

@@ -56,6 +56,7 @@ private HelpCommentsParser(CommandInfo commandInfo, List<string> parameterDescri
         private readonly Language.CommentHelpInfo _sections = new Language.CommentHelpInfo();
         private readonly Dictionary<string, string> _parameters = new Dictionary<string, string>();
         private readonly List<string> _examples = new List<string>();
+        private readonly List<string> _exampleTitles = new List<string>();
         private readonly List<string> _inputs = new List<string>();
         private readonly List<string> _outputs = new List<string>();
         private readonly List<string> _links = new List<string>();
@@ -355,22 +356,28 @@ internal XmlDocument BuildXmlFromComments()
             {
                 XmlElement examples = _doc.CreateElement("command:examples", commandURI);
                 int count = 1;
-                foreach (string example in _examples)
+                for (int exampleIndex = 0; exampleIndex < _examples.Count; exampleIndex++)
                 {
+                    string exampleBody = _examples[exampleIndex];
+                    string exampleTitle = _exampleTitles[exampleIndex];
                     XmlElement example_node = _doc.CreateElement("command:example", commandURI);
 
-                    // The title is automatically generated
+                    // The title is automatically generated, with an optional custom title appended
                     XmlElement title = _doc.CreateElement("maml:title", mamlURI);
-                    string titleStr = string.Format(CultureInfo.InvariantCulture,
-                        "\t\t\t\t-------------------------- {0} {1} --------------------------",
-                        HelpDisplayStrings.ExampleUpperCase, count++);
+                    string titleStr = string.IsNullOrEmpty(exampleTitle)
+                        ? string.Format(CultureInfo.InvariantCulture,
+                            "\t\t\t\t-------------------------- {0} {1} --------------------------",
+                            HelpDisplayStrings.ExampleUpperCase, count++)
+                        : string.Format(CultureInfo.InvariantCulture,
+                            "\t\t\t\t-------------------------- {0} {1}: {2} --------------------------",
+                            HelpDisplayStrings.ExampleUpperCase, count++, exampleTitle);
                     XmlText title_text = _doc.CreateTextNode(titleStr);
                     example_node.AppendChild(title).AppendChild(title_text);
 
                     string prompt_str;
                     string code_str;
                     string remarks_str;
-                    GetExampleSections(example, out prompt_str, out code_str, out remarks_str);
+                    GetExampleSections(exampleBody, out prompt_str, out code_str, out remarks_str);
 
                     // Introduction (usually the prompt)
                     XmlElement introduction = _doc.CreateElement("maml:introduction", mamlURI);
@@ -719,9 +726,21 @@ private bool AnalyzeCommentBlock(List<string> commentLines)
                 {
                     directiveFound = true;
 
-                    if (match.Groups[3].Success)
+                    string sectionName = match.Groups[1].Value.ToUpperInvariant();
+
+                    // .EXAMPLE is the only directive that is valid both with and without inline
+                    // text, so it is handled once here instead of in both switches below. Adding
+                    // the title and the body together keeps _exampleTitles and _examples the same
+                    // length by construction. Groups[3].Value is the empty string when the
+                    // optional group did not participate, which is the untitled form.
+                    if (sectionName == "EXAMPLE")
+                    {
+                        _exampleTitles.Add(match.Groups[3].Value.Trim());
+                        _examples.Add(GetSection(commentLines, ref i));
+                    }
+                    else if (match.Groups[3].Success)
                     {
-                        switch (match.Groups[1].Value.ToUpperInvariant())
+                        switch (sectionName)
                         {
                             case "PARAMETER":
                                 {
@@ -753,7 +772,7 @@ private bool AnalyzeCommentBlock(List<string> commentLines)
                     }
                     else
                     {
-                        switch (match.Groups[1].Value.ToUpperInvariant())
+                        switch (sectionName)
                         {
                             case "SYNOPSIS":
                                 _sections.Synopsis = GetSection(commentLines, ref i);
@@ -767,9 +786,6 @@ private bool AnalyzeCommentBlock(List<string> commentLines)
                             case "LINK":
                                 _links.Add(GetSection(commentLines, ref i).Trim());
                                 break;
-                            case "EXAMPLE":
-                                _examples.Add(GetSection(commentLines, ref i));
-                                break;
                             case "INPUTS":
                                 _inputs.Add(GetSection(commentLines, ref i));
                                 break;
@@ -797,6 +813,7 @@ private bool AnalyzeCommentBlock(List<string> commentLines)
             }
 
             _sections.Examples = new ReadOnlyCollection<string>(_examples);
+            _sections.ExampleTitles = new ReadOnlyCollection<string>(_exampleTitles);
             _sections.Inputs = new ReadOnlyCollection<string>(_inputs);
             _sections.Outputs = new ReadOnlyCollection<string>(_outputs);
             _sections.Links = new ReadOnlyCollection<string>(_links);