feat(plugin-auto-nav-sidebar): support index as the dir click section and custom-link context

.changeset/two-lizards-rule.md

@@ -0,0 +1,6 @@
+---
+'@rspress/plugin-auto-nav-sidebar': patch
+'@rspress/theme-default': minor
+---
+
+support index convention and custom-link context

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/_meta.json

@@ -0,0 +1,7 @@
+[
+  {
+    "text": "Guide",
+    "link": "/guide/",
+    "activeMatch": "/guide/"
+  }
+]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/_meta.json

@@ -0,0 +1,33 @@
+[
+  "index",
+  {
+    "type": "dir",
+    "label": "index-md-convention",
+    "name": "index-md-convention"
+  },
+  {
+    "type": "dir",
+    "label": "index-mdx-convention",
+    "name": "index-mdx-convention"
+  },
+  {
+    "type": "dir",
+    "label": "same-name",
+    "name": "same-name"
+  },
+  {
+    "type": "dir",
+    "label": "index-in-meta",
+    "name": "index-in-meta"
+  },
+  {
+    "type": "dir",
+    "label": "single-md",
+    "name": "single-md"
+  },
+  {
+    "type": "dir",
+    "label": "single-mdx",
+    "name": "single-mdx"
+  }
+]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-in-meta/_meta.json

@@ -0,0 +1 @@
+["index"]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-in-meta/index.md

@@ -0,0 +1,5 @@
+---
+context: 'context-index-in-meta'
+---
+
+# index-in-meta inner Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-md-convention/_meta.json

@@ -0,0 +1 @@
+[]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-md-convention/index.md

@@ -0,0 +1,5 @@
+---
+context: 'context-index-md-convention'
+---
+
+# index-md-convention inner Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-mdx-convention/_meta.json

@@ -0,0 +1 @@
+[]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index-mdx-convention/index.mdx

@@ -0,0 +1,5 @@
+---
+context: 'context-index-mdx-convention'
+---
+
+# index-mdx-convention inner Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/index.md

@@ -0,0 +1 @@
+# /guide Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/same-name.mdx

@@ -0,0 +1,5 @@
+---
+context: 'context-same-name'
+---
+
+# same-name outer Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/same-name/_meta.json

@@ -0,0 +1 @@
+[]

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/single-md/index.md

@@ -0,0 +1,5 @@
+---
+context: 'context-single-md'
+---
+
+# single-md inner Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/guide/single-mdx/index.mdx

@@ -0,0 +1,5 @@
+---
+context: 'context-single-mdx'
+---
+
+# single-mdx inner Page

e2e/fixtures/auto-nav-sidebar-dir-convention/doc/index.md

@@ -0,0 +1 @@
+# Hello World

e2e/fixtures/auto-nav-sidebar-dir-convention/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@rspress-fixture/rspress-auto-nav-sidebar-dir-convention",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "rspress dev",
+    "build": "rspress build",
+    "preview": "rspress preview"
+  },
+  "dependencies": {
+    "rspress": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^18.11.17"
+  }
+}

e2e/fixtures/auto-nav-sidebar-dir-convention/rspress.config.ts

@@ -0,0 +1,6 @@
+import * as path from 'node:path';
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  root: path.join(__dirname, 'doc'),
+});

e2e/fixtures/auto-nav-sidebar-dir-convention/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "jsx": "react"
+  }
+}

e2e/fixtures/auto-nav-sidebar/doc/api/_meta.json

@@ -16,6 +16,17 @@
     "label": "Client API",
     "context": "client-api"
   },
+  {
+    "type": "custom-link",
+    "label": "Rspack Official Docsite",
+    "link": "https://rspack.dev/",
+    "context": "rspack-official-docsite-custom-link"
+  },
+  {
+    "type": "dir",
+    "name": "link",
+    "label": "Link"
+  },
   "commands",
   "single-page"
 ]

e2e/fixtures/auto-nav-sidebar/doc/api/link/_meta.json

@@ -0,0 +1,8 @@
+[
+  {
+    "type": "custom-link",
+    "label": "Inner SideBar Rspack Official Docsite",
+    "link": "https://rspack.dev/",
+    "context": "rspack-official-docsite-custom-link"
+  }
+]

e2e/tests/auto-nav-sidebar-dir-convension.test.ts

@@ -0,0 +1,119 @@
+import { expect, test } from '@playwright/test';
+import path from 'node:path';
+import { getPort, killProcess, runDevCommand } from '../utils/runCommands';
+
+const fixtureDir = path.resolve(__dirname, '../fixtures');
+
+test.describe('Auto nav and sidebar dir convention', async () => {
+  let appPort;
+  let app;
+  test.beforeAll(async () => {
+    const appDir = path.join(fixtureDir, 'auto-nav-sidebar-dir-convention');
+    appPort = await getPort();
+    app = await runDevCommand(appDir, appPort);
+  });
+
+  test.afterAll(async () => {
+    if (app) {
+      await killProcess(app);
+    }
+  });
+
+  test('Should render sidebar with index convention correctly', async ({
+    page,
+  }) => {
+    await page.goto(`http://localhost:${appPort}/guide/`, {
+      waitUntil: 'networkidle',
+    });
+
+    // take the sidebar, properly a section or a tag
+    const sidebar =
+      (await page.$$(
+        `.rspress-sidebar .rspress-scrollbar > nav > section,
+      .rspress-sidebar .rspress-scrollbar > nav > a`,
+      )) ?? [];
+    expect(sidebar.length).toBe(7);
+    const sidebarTexts = await Promise.all(
+      sidebar.map(element => element.textContent()),
+    );
+    expect(sidebarTexts.join(',')).toEqual(
+      [
+        '/guide Page',
+        'index-md-convention',
+        'index-mdx-convention',
+        'same-name',
+        'index-in-metaindex-in-meta inner Page', // index-in-meta has the sub sidebar
+        'single-mdsingle-md inner Page', // single-md has the sub sidebar
+        'single-mdxsingle-mdx inner Page', // single-mdx has the sub sidebar
+      ].join(','),
+    );
+  });
+
+  test('Should click the directory and navigate to the index page', async ({
+    page,
+  }) => {
+    await page.goto(`http://localhost:${appPort}/guide/`, {
+      waitUntil: 'networkidle',
+    });
+    await page.click('.rspress-scrollbar nav section div');
+    expect(page.url()).toBe(
+      `http://localhost:${appPort}/guide/index-md-convention.html`,
+    );
+  });
+
+  test('Should generate data-context in dir convention', async ({ page }) => {
+    await page.goto(`http://localhost:${appPort}/guide/`, {
+      waitUntil: 'networkidle',
+    });
+
+    const sidebarGroupSections = await page.$$('.rspress-sidebar-section');
+
+    // first level
+    const contexts1 = await page.evaluate(
+      sidebars =>
+        sidebars?.map(sidebar => sidebar.getAttribute('data-context')),
+      sidebarGroupSections,
+    );
+    expect(contexts1.join(',')).toEqual(
+      [
+        'context-index-md-convention',
+        'context-index-mdx-convention',
+        'context-same-name',
+        '',
+        '',
+        '',
+      ].join(','),
+    );
+
+    const sidebarGroupCollapses = await page.$$('.rspress-sidebar-collapse');
+    const contexts2 = await page.evaluate(
+      sidebars =>
+        sidebars?.map(sidebar => sidebar.getAttribute('data-context')),
+      sidebarGroupCollapses,
+    );
+    expect(contexts2.join(',')).toEqual(
+      [
+        'context-index-md-convention',
+        'context-index-mdx-convention',
+        'context-same-name',
+        '',
+        '',
+        '',
+      ].join(','),
+    );
+
+    const sidebarGroupItems = await page.$$('.rspress-sidebar-item');
+    const contexts3 = await page.evaluate(
+      sidebarGroupConfig =>
+        sidebarGroupConfig?.map(sidebarItem =>
+          sidebarItem.getAttribute('data-context'),
+        ),
+      sidebarGroupItems,
+    );
+    expect(contexts3.join(',')).toEqual(
+      ['context-index-in-meta', 'context-single-md', 'context-single-mdx'].join(
+        ',',
+      ),
+    );
+  });
+});

e2e/tests/auto-nav-sidebar.test.ts

@@ -1,4 +1,4 @@
-import { expect, test } from '@playwright/test';
+import { type ElementHandle, expect, test } from '@playwright/test';
 import path from 'node:path';
 import { getPort, killProcess, runDevCommand } from '../utils/runCommands';
 import { getNavbar, getSidebar } from '../utils/getSideBar';
@@ -176,35 +176,47 @@ test.describe('Auto nav and sidebar test', async () => {
       waitUntil: 'networkidle',
     });
 
+    function getDataContextFromElements(
+      elements: ElementHandle<SVGElement | HTMLElement>[],
+    ) {
+      return page.evaluate(
+        sidebars =>
+          sidebars?.map(sidebar => sidebar.getAttribute('data-context')),
+        elements,
+      );
+    }
+
     const sidebarGroupSections = await page.$$('.rspress-sidebar-section');
-    const contexts1 = await page.evaluate(
-      sidebars =>
-        sidebars?.map(sidebar => sidebar.getAttribute('data-context')),
-      sidebarGroupSections,
-    );
-    expect(contexts1.join(',')).toEqual(
-      ['config', null, 'client-api'].join(','),
+    const c1 = await getDataContextFromElements(sidebarGroupSections);
+    expect(c1.join(',')).toEqual(
+      ['config', null, 'client-api', null].join(','),
     );
 
     const sidebarGroupCollapses = await page.$$('.rspress-sidebar-collapse');
-    const contexts2 = await page.evaluate(
+    const c2 = await page.evaluate(
       sidebars =>
         sidebars?.map(sidebar => sidebar.getAttribute('data-context')),
       sidebarGroupCollapses,
     );
-    expect(contexts2.join(',')).toEqual(
-      ['config', null, 'client-api'].join(','),
+    expect(c2.join(',')).toEqual(
+      ['config', null, 'client-api', null].join(','),
     );
 
     const sidebarGroupItems = await page.$$('.rspress-sidebar-item');
-    const contexts3 = await page.evaluate(
-      sidebarGroupConfig =>
-        sidebarGroupConfig?.map(sidebarItem =>
-          sidebarItem.getAttribute('data-context'),
-        ),
-      sidebarGroupItems,
+    const c3 = await getDataContextFromElements(sidebarGroupItems);
+    expect(c3?.[2]).toEqual('front-matter');
+    expect(c3?.[3]).toEqual('config-build');
+
+    // custom link should work
+    const customLinkItems = await page.$$(
+      '[data-context="rspack-official-docsite-custom-link"]',
+    );
+    const c4 = await Promise.all(customLinkItems.map(i => i.textContent()));
+
+    expect(c4.join(',')).toEqual(
+      ['Rspack Official Docsite', 'Inner SideBar Rspack Official Docsite'].join(
+        ',',
+      ),
     );
-    expect(contexts3?.[2]).toEqual('front-matter');
-    expect(contexts3?.[3]).toEqual('config-build');
   });
 });

packages/document/docs/en/guide/basic/auto-nav-sidebar.mdx

@@ -87,6 +87,17 @@ export type SideMetaItem =
   | {
       type: 'divider';
       dashed?: boolean;
+    }
+  | {
+      type: 'section-header';
+      label: string;
+      tag?: string;
+    }
+  | {
+      type: 'custom-link';
+      label: string;
+      link: string;
+      context?: string;
     };
 ```
 
@@ -222,8 +233,9 @@ In the case of describing **custom link**, the types are as follows:
 ```ts
 {
   type: 'custom-link';
-  link: string;
   label: string;
+  link: string;
+  context?: string;
 }
 ```
 

packages/document/docs/zh/guide/basic/auto-nav-sidebar.mdx

@@ -92,6 +92,12 @@ export type SideMetaItem =
       type: 'section-header';
       label: string;
       tag?: string;
+    }
+  | {
+      type: 'custom-link';
+      label: string;
+      link: string;
+      context?: string;
     };
 ```
 
@@ -229,6 +235,7 @@ docs
   type: 'custom-link';
   label: string;
   link: string;
+  context?: string;
 }
 ```