Fix right-side navigation order when snippets are included (#1906)

* Initial plan

* 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]>

* Final fix and test for snippet heading order issue

- Updated test to properly verify heading order in PageTableOfContent
- Verified fix works correctly with manual testing
- Snippet headings now appear in correct document order

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

* Add comprehensive tests for include directive positioning

- Added test for include before headings (IncludeBeforeHeadingsOrderTests)
- Added test for include in middle of headings (IncludeInMiddleOfHeadingsOrderTests)
- Tests verify correct heading order for all include positions
- All 598 unit tests pass successfully

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

* Add comprehensive tests for stepper components with includes

- Added IncludeWithStepperOrderTests: Tests stepper components combined with include directives
- Added StepperBeforeIncludeOrderTests: Tests stepper components before include directives
- Tests verify correct TOC ordering for stepper steps from both main document and included snippets
- All 604 unit tests pass successfully (6 new tests added)

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

* Refactor tests to use numbered words as headings

- Changed all realistic headings to numbered words (One, Two, Three, etc.)
- Updated all expected TOC orders to follow sequential numbering
- Makes it easy to verify correct heading order in test output
- All 604 unit tests pass successfully

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

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
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>()