Fix heading order issue when snippets are included

- Modified GetAnchors method to preserve line number from include directive
- Included snippet headings now appear at the correct position in TOC
- Changed from assigning line 0 to using actual include block line number
- This ensures right-side navigation respects document order

Co-authored-by: reakaleek <[email protected]>

Author: Copilot

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -253,12 +253,16 @@ public static List<PageTocItem> GetAnchors(
 					|| file is not SnippetFile snippet)
 					return null;
 
-				return snippet.GetAnchors(set, parser, frontMatter);
+				var anchors = snippet.GetAnchors(set, parser, frontMatter);
+				return new { Block = i, Anchors = anchors };
 			})
 			.Where(i => i is not null)
 			.ToArray();
 
-		var includedTocs = includes.SelectMany(i => i!.TableOfContentItems).ToArray();
+		var includedTocs = includes
+			.SelectMany(i => i!.Anchors!.TableOfContentItems
+				.Select(item => new { TocItem = item, i.Block.Line }))
+			.ToArray();
 
 		// Collect headings from standard markdown
 		var headingTocs = document
@@ -308,7 +312,7 @@ public static List<PageTocItem> GetAnchors(
 
 		var toc = headingTocs
 			.Concat(stepperTocs)
-			.Concat(includedTocs.Select(item => new { TocItem = item, Line = 0 }))
+			.Concat(includedTocs)
 			.OrderBy(item => item.Line)
 			.Select(item => item.TocItem)
 			.Select(toc => subs.Count == 0
@@ -318,7 +322,7 @@ public static List<PageTocItem> GetAnchors(
 					: toc)
 			.ToList();
 
-		var includedAnchors = includes.SelectMany(i => i!.Anchors).ToArray();
+		var includedAnchors = includes.SelectMany(i => i!.Anchors!.Anchors).ToArray();
 		anchors =
 		[
 			..document.Descendants<DirectiveBlock>()

tests/Elastic.Markdown.Tests/FileInclusion/HeadingOrderTests.cs

@@ -0,0 +1,78 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// 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 System.IO.Abstractions.TestingHelpers;
+using Elastic.Markdown.IO;
+using Elastic.Markdown.Myst.Directives.Include;
+using Elastic.Markdown.Tests.Directives;
+using FluentAssertions;
+
+namespace Elastic.Markdown.Tests.FileInclusion;
+
+public class IncludeHeadingOrderTests(ITestOutputHelper output) : DirectiveTest<IncludeBlock>(output,
+"""
+## Check status, stop, and restart SLM
+### Get SLM status 
+### Stop SLM 
+### Start SLM
+## Check status, stop, and restart ILM
+
+:::{include} _snippets/ilm-status.md
+:::
+"""
+)
+{
+	protected override void AddToFileSystem(MockFileSystem fileSystem)
+	{
+		// language=markdown
+		var inclusion = """
+### Get ILM status
+### Stop ILM 
+### Start ILM
+""";
+		fileSystem.AddFile(@"docs/_snippets/ilm-status.md", inclusion);
+	}
+
+	[Fact]
+	public void ParsesBlock() => Block.Should().NotBeNull();
+
+	[Fact]
+	public void IncludesSnippetAfterMainContent() =>
+		Html.Should().Contain("Get SLM status").And.Contain("Get ILM status");
+
+	[Fact]
+	public void TableOfContentsRespectsOrder()
+	{
+		// Get the table of contents from the file
+		var toc = File.PageTableOfContent;
+		var headings = toc.Select(kvp => kvp.Value.Heading).ToList();
+
+		// The headings should appear in document order:
+		// 1. Check status, stop, and restart SLM
+		// 2. Get SLM status
+		// 3. Stop SLM
+		// 4. Start SLM
+		// 5. Check status, stop, and restart ILM
+		// 6. Get ILM status (from included snippet)
+		// 7. Stop ILM (from included snippet)
+		// 8. Start ILM (from included snippet)
+
+		headings.Should().HaveCount(8);
+
+		// Check the order is correct
+		var expectedOrder = new[]
+		{
+			"Check status, stop, and restart SLM",
+			"Get SLM status",
+			"Stop SLM",
+			"Start SLM",
+			"Check status, stop, and restart ILM",
+			"Get ILM status",
+			"Stop ILM",
+			"Start ILM"
+		};
+
+		headings.Should().ContainInOrder(expectedOrder);
+	}
+}