Fix right-side navigation order when snippets are included

[Copilot]

Fixed heading order issue when snippets are included

Problem

When using :::{include} _snippets/file.md directives, the right-side "On this page" navigation displayed snippet headings at the top instead of respecting their document position, causing confusing navigation order.

Root Cause

In the GetAnchors method in MarkdownFile.cs:

1. Regular headings were collected with their actual line numbers from the document
2. Snippet headings were collected but assigned a line number of 0
3. When sorted by line number, snippet headings appeared first

Solution

• Explore repository structure and understand the codebase
• Build the project and run tests to verify current functionality
• Analyze the GetAnchors method in MarkdownFile.cs
• Identify root cause: snippet headings get line number 0 in sorting
• Create a focused test that reproduces the issue
• Fix the line number assignment for included snippets
• Verify the fix resolves the ordering issue
• Run tests to ensure no regressions
• Add comprehensive tests for different include positions
• Add tests with stepper components that also contribute to TOC
• Refactor tests to use numbered words for clear ordering verification

Changes Made

Modified the GetAnchors method to:

1. Track the relationship between IncludeBlock directives and their snippets
2. Use the include block's line number for all headings from that snippet
3. Maintain correct ordering when sorting by line number

Testing Coverage

Added comprehensive tests covering five scenarios using numbered words (One, Two, Three, etc.) for easy verification:

1. Include at end: Include directive after main headings
2. Include at beginning: Include directive before any main headings
3. Include in middle: Include directive between main heading sections
4. Include with stepper: Stepper components combined with include directives
5. Stepper before include: Stepper components before include directives

All tests verify that the table of contents respects document order regardless of where include directives are positioned and whether stepper components are involved. The numbered headings make it immediately apparent that the ordering is correct (One, Two, Three, Four, Five, Six, Seven, Eight, etc.).

Verification

Created manual test showing the fix works:

Before Fix:

• Get ILM status (❌ from snippet, appears first)
• Stop ILM (❌ from snippet)
• Start ILM (❌ from snippet)
• Check status, stop, and restart SLM (main doc)
• Get SLM status (main doc)
• Stop SLM (main doc)
• Start SLM (main doc)
• Check status, stop, and restart ILM (main doc)

After Fix:

• Check status, stop, and restart SLM (✅ correct order)
• Get SLM status
• Stop SLM
• Start SLM
• Check status, stop, and restart ILM
• Get ILM status (✅ snippet appears after include directive)
• Stop ILM (✅ snippet)
• Start ILM (✅ snippet)

Now snippet headings appear at the position where the include directive is located in the main document, preserving the intended document order for both regular headings and stepper components.

Fixes #1880.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[reakaleek]

LGTM