Fix stepper heading levels from snippets

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -211,8 +211,27 @@ public static List<PageTocItem> GetAnchors(
 			.ToArray();
 
 		var includedTocs = includes
-			.SelectMany(i => i!.Anchors!.TableOfContentItems
-				.Select(item => new { TocItem = item, i.Block.Line }))
+			.SelectMany(i =>
+			{
+				// Calculate the heading level context at the include block position
+				var precedingLevel = GetPrecedingHeadingLevel(i!.Block);
+
+				return i.Anchors!.TableOfContentItems
+					.Select(item =>
+					{
+						// Only adjust stepper steps, not regular headings
+						// Stepper steps default to level 2 when parsed in isolation (no preceding heading in snippet),
+						// but should be relative to the preceding heading in the parent document
+						var adjustedItem = item;
+						if (item.IsStepperStep && precedingLevel.HasValue && item.Level == 2)
+						{
+							// The step was parsed without context (defaulted to h2)
+							// Adjust it to be one level deeper than the preceding heading
+							adjustedItem = item with { Level = Math.Min(precedingLevel.Value + 1, 6) };
+						}
+						return new { TocItem = adjustedItem, i.Block.Line };
+					});
+			})
 			.ToArray();
 
 		// Collect headings from standard markdown
@@ -255,7 +274,8 @@ public static List<PageTocItem> GetAnchors(
 					{
 						Heading = processedTitle,
 						Slug = step.Anchor,
-						Level = step.HeadingLevel // Use dynamic heading level
+						Level = step.HeadingLevel, // Use dynamic heading level
+						IsStepperStep = true
 					},
 					step.Line
 				};
@@ -300,6 +320,38 @@ private static bool IsNestedInOtherDirective(DirectiveBlock block)
 		return false;
 	}
 
+	/// <summary>
+	/// Finds the heading level that precedes the given block in the document.
+	/// Used to provide context for included snippets so stepper heading levels
+	/// can be adjusted relative to the parent document's structure.
+	/// </summary>
+	private static int? GetPrecedingHeadingLevel(MarkdownObject block)
+	{
+		// Find the document root
+		var current = block;
+		while (current is ContainerBlock container && container.Parent != null)
+			current = container.Parent;
+
+		if (current is not ContainerBlock root)
+			return null;
+
+		// Find all blocks and locate this one
+		var allBlocks = root.Descendants().ToList();
+		var thisIndex = allBlocks.IndexOf(block);
+
+		if (thisIndex == -1)
+			return null;
+
+		// Look backwards for the most recent heading
+		for (var i = thisIndex - 1; i >= 0; i--)
+		{
+			if (allBlocks[i] is HeadingBlock heading)
+				return heading.Level;
+		}
+
+		return null;
+	}
+
 	private YamlFrontMatter ProcessYamlFrontMatter(MarkdownDocument document)
 	{
 		if (document.FirstOrDefault() is not YamlFrontMatterBlock yaml)

src/Elastic.Markdown/MarkdownLayoutViewModel.cs

@@ -37,4 +37,11 @@ public record PageTocItem
 	public required string Heading { get; init; }
 	public required string Slug { get; init; }
 	public required int Level { get; init; }
+
+	/// <summary>
+	/// Indicates if this ToC item came from a stepper step.
+	/// Used to distinguish stepper steps (which may need level adjustment in includes)
+	/// from regular headings (which should preserve their levels).
+	/// </summary>
+	public bool IsStepperStep { get; init; }
 }