Plugin Docs CLI: Always sort root index.md first in manifest

packages/plugin-docs-cli/src/__fixtures__/no-position-index-docs/guide.md

@@ -0,0 +1,9 @@
+---
+title: Guide
+description: User guide
+sidebar_position: 1
+---
+
+# Guide
+
+This guide page has sidebar_position: 1.

packages/plugin-docs-cli/src/__fixtures__/no-position-index-docs/index.md

@@ -0,0 +1,8 @@
+---
+title: Overview
+description: Plugin overview page
+---
+
+# Overview
+
+This is the overview page with no sidebar_position set.

packages/plugin-docs-cli/src/scanner.test.ts

@@ -15,6 +15,14 @@ describe('scanDocsFolder', () => {
     expect(result.manifest.pages).toHaveLength(4); // home, guide, advanced, config
   });
 
+  it('should sort root index.md first even when sidebar_position is not set', async () => {
+    const noPositionPath = join(__dirname, '__fixtures__', 'no-position-index-docs');
+    const result = await scanDocsFolder(noPositionPath);
+
+    expect(result.manifest.pages[0].slug).toBe('index');
+    expect(result.manifest.pages[0].file).toBe('index.md');
+  });
+
   it('should sort pages by sidebar_position', async () => {
     const result = await scanDocsFolder(testDocsPath);
 

packages/plugin-docs-cli/src/scanner.ts

@@ -204,11 +204,12 @@ function treeToPages(node: TreeNode): Page[] {
     }
   }
 
-  // convert children to array and sort by sidebar_position
-  const sortedEntries = childEntries.sort(
-    (a, b) =>
-      (a[1].file?.frontmatter.sidebar_position ?? Infinity) - (b[1].file?.frontmatter.sidebar_position ?? Infinity)
-  );
+  // convert children to array and sort by sidebar_position; root index.md always first
+  const sortedEntries = childEntries.sort((a, b) => {
+    if (a[0] === 'index.md') { return -1; }
+    if (b[0] === 'index.md') { return 1; }
+    return (a[1].file?.frontmatter.sidebar_position ?? Infinity) - (b[1].file?.frontmatter.sidebar_position ?? Infinity);
+  });
 
   for (const [name, child] of sortedEntries) {
     if (child.file) {