Allow subs in stepper headings (#1659)

* Add subs to stepper headings

* Docs sample

* Use renderer

* Fix linter warning

* Fix another warning

* Use Markdig

* Proper renderer

* Move subs logic

* Clean up

* Rewrite part

Author: theletterf

docs/_docset.yml

@@ -16,6 +16,7 @@ subs:
   ech:  "Elastic Cloud Hosted"
   serverless-full: "Elastic Cloud Serverless"
   ecloud: "Elastic Cloud"
+  dbuild: "docs-builder"
 
 features:
   primary-nav: false

docs/contribute/locally.md

@@ -145,7 +145,7 @@ cd docs-content
 ```
 :::::
 
-:::::{step} Run docs-builder
+:::::{step} Run {{dbuild}}  
 
 Run the `docs-builder` binary with the `serve` command to build and serve the content set to [http://localhost:3000](http://localhost:3000). If necessary, specify the path to the `docset.yml` file that you want to build with `-p`.
 

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -289,15 +289,25 @@ public static List<PageTocItem> GetAnchors(
 			.OfType<StepBlock>()
 			.Where(step => !string.IsNullOrEmpty(step.Title))
 			.Where(step => !IsNestedInOtherDirective(step))
-			.Select(step => new
+			.Select(step =>
 			{
-				TocItem = new PageTocItem
+				var processedTitle = step.Title;
+				// Apply substitutions to step titles
+				if (subs.Count > 0 && processedTitle.AsSpan().ReplaceSubstitutions(subs, set.Context.Collector, out var replacement))
 				{
-					Heading = step.Title,
-					Slug = step.Anchor,
-					Level = step.HeadingLevel // Use dynamic heading level
-				},
-				step.Line
+					processedTitle = replacement;
+				}
+
+				return new
+				{
+					TocItem = new PageTocItem
+					{
+						Heading = processedTitle,
+						Slug = step.Anchor,
+						Level = step.HeadingLevel // Use dynamic heading level
+					},
+					step.Line
+				};
 			});
 
 		var toc = headingTocs

src/Elastic.Markdown/Myst/Directives/Stepper/StepView.cshtml

@@ -6,32 +6,32 @@
 		{
 			case 1:
 				<h1 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h1>
 				break;
 			case 2:
 				<h2 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h2>
 				break;
 			case 3:
 				<h3 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h3>
 				break;
 			case 4:
 				<h4 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h4>
 				break;
 			case 5:
 				<h5 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h5>
 				break;
 			default:
 				<h6 id="@Model.Anchor">
-					<a href="#@Model.Anchor">@Model.Title</a>
+					<a href="#@Model.Anchor">@Model.RenderTitle()</a>
 				</h6>
 				break;
 		}

src/Elastic.Markdown/Myst/Directives/Stepper/StepViewModel.cs

@@ -2,11 +2,51 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Markdown.Helpers;
+using Elastic.Markdown.IO;
+using Markdig.Syntax;
+using Markdig.Syntax.Inlines;
+using Microsoft.AspNetCore.Html;
+
 namespace Elastic.Markdown.Myst.Directives.Stepper;
 
 public class StepViewModel : DirectiveViewModel
 {
 	public required string Title { get; init; }
 	public required string Anchor { get; init; }
 	public required int HeadingLevel { get; init; }
+
+	/// <summary>
+	/// Renders the title with full markdown processing (substitutions, links, emphasis, etc.)
+	/// </summary>
+	public HtmlString RenderTitle()
+	{
+		// Parse the title as markdown with full pipeline (including substitutions)
+		var directiveBlock = (DirectiveBlock)DirectiveBlock;
+
+		// Get the YamlFrontMatter from the original document to support local substitutions
+		var originalContext = directiveBlock.GetData("context") as ParserContext;
+		var yamlFrontMatter = originalContext?.YamlFrontMatter;
+
+		var context = new ParserContext(new ParserState(directiveBlock.Build)
+		{
+			MarkdownSourcePath = directiveBlock.CurrentFile,
+			YamlFrontMatter = yamlFrontMatter,
+			DocumentationFileLookup = (path) => null!,
+			CrossLinkResolver = null!
+		});
+
+		var document = Markdig.Markdown.Parse(Title, MarkdownParser.Pipeline, context);
+
+		if (document.FirstOrDefault() is not Markdig.Syntax.ParagraphBlock firstBlock)
+			return new(Title);
+
+		// Use the HTML renderer to render the inline content with full processing
+		var subscription = DocumentationObjectPoolProvider.HtmlRendererPool.Get();
+		_ = subscription.HtmlRenderer.WriteLeafInline(firstBlock);
+
+		var result = subscription.RentedStringBuilder?.ToString() ?? Title;
+		DocumentationObjectPoolProvider.HtmlRendererPool.Return(subscription);
+		return new(result);
+	}
 }

src/Elastic.Markdown/Myst/Directives/Stepper/StepperBlock.cs

@@ -26,6 +26,7 @@ public class StepBlock(DirectiveBlockParser parser, ParserContext context) : Dir
 	public override void FinalizeAndValidate(ParserContext context)
 	{
 		Title = Arguments ?? string.Empty;
+
 		Anchor = Prop("anchor") ?? Title.Slugify();
 
 		// Calculate heading level based on preceding heading