fix(auto-nav-sidebar): correct both _meta.json and _nav.json exist behavior (#2453)

SoonIter · web-flow · commit 72e72b1632ae · 2025-08-07T14:23:15.000+08:00
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/_nav.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/_nav.json
@@ -0,0 +1,6 @@
+[
+  {
+    "text": "Guide",
+    "link": "/guide"
+  }
+]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide.md
@@ -0,0 +1 @@
+# v1 Guide
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide/_meta.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide/_meta.json
@@ -0,0 +1 @@
+["feature"]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide/feature.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/guide/feature.md
@@ -0,0 +1,3 @@
+# Feature V1
+
+This is a feature of V1.
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/index.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/en/index.md
@@ -0,0 +1,7 @@
+# v1
+
+:::tip TIP
+
+This is a TIP.
+
+:::
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/_nav.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/_nav.json
@@ -0,0 +1,6 @@
+[
+  {
+    "text": "指引",
+    "link": "/guide"
+  }
+]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide.md
@@ -0,0 +1 @@
+# v1 指南
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide/_meta.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide/_meta.json
@@ -0,0 +1 @@
+["feature"]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide/feature.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/guide/feature.md
@@ -0,0 +1,3 @@
+# 功能 V1
+
+这是 V1 的功能。
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/index.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v1/zh/index.md
@@ -0,0 +1,7 @@
+# v1 中文
+
+:::tip 提示
+
+这是一个提示。
+
+:::
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/_nav.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/_nav.json
@@ -0,0 +1,6 @@
+[
+  {
+    "text": "Guide",
+    "link": "/guide"
+  }
+]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide.md
@@ -0,0 +1 @@
+# v2 Guide
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide/_meta.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide/_meta.json
@@ -0,0 +1 @@
+["feature"]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide/feature.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/guide/feature.md
@@ -0,0 +1,3 @@
+# Feature V2
+
+This is a feature of V2.
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/index.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/en/index.md
@@ -0,0 +1,7 @@
+# v2
+
+:::tip TIP
+
+This is a TIP.
+
+:::
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/_nav.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/_nav.json
@@ -0,0 +1,6 @@
+[
+  {
+    "text": "指引",
+    "link": "/guide"
+  }
+]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide.md
@@ -0,0 +1 @@
+# v2 指南
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide/_meta.json b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide/_meta.json
@@ -0,0 +1 @@
+["feature"]
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide/feature.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/guide/feature.md
@@ -0,0 +1,3 @@
+# 功能 V2
+
+这是 V2 的功能
diff --git a/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/index.md b/packages/core/src/node/auto-nav-sidebar/fixtures/docs-multi-version/v2/zh/index.md
@@ -0,0 +1,7 @@
+# v2 中文
+
+:::tip 提示
+
+这是一个 TIP
+
+:::
diff --git a/packages/core/src/node/auto-nav-sidebar/locales.test.ts b/packages/core/src/node/auto-nav-sidebar/locales.test.ts
@@ -212,4 +212,72 @@ describe('walk', () => {
       ]
     `);
   });
+  it('multiVersion', async () => {
+    const docsDir = path.join(__dirname, './fixtures/docs-multi-version');
+    const result = await processLocales(['zh', 'en'], ['v1', 'v2'], docsDir, [
+      '.md',
+      '.mdx',
+      '.tsx',
+    ]);
+    expect(result).toMatchInlineSnapshot(`
+      [
+        {
+          "nav": {
+            "v1": [
+              {
+                "link": "/guide",
+                "text": "指引",
+              },
+            ],
+            "v2": [
+              {
+                "link": "/guide",
+                "text": "指引",
+              },
+            ],
+          },
+          "sidebar": {
+            "/guide": [
+              {
+                "_fileKey": "v2/zh/guide/feature",
+                "context": undefined,
+                "link": "/v2/zh/guide/feature",
+                "overviewHeaders": undefined,
+                "tag": undefined,
+                "text": "功能 V2",
+              },
+            ],
+          },
+        },
+        {
+          "nav": {
+            "v1": [
+              {
+                "link": "/guide",
+                "text": "Guide",
+              },
+            ],
+            "v2": [
+              {
+                "link": "/guide",
+                "text": "Guide",
+              },
+            ],
+          },
+          "sidebar": {
+            "/guide": [
+              {
+                "_fileKey": "v2/en/guide/feature",
+                "context": undefined,
+                "link": "/v2/en/guide/feature",
+                "overviewHeaders": undefined,
+                "tag": undefined,
+                "text": "Feature V2",
+              },
+            ],
+          },
+        },
+      ]
+    `);
+  });
 });
diff --git a/packages/core/src/node/auto-nav-sidebar/walk.test.ts b/packages/core/src/node/auto-nav-sidebar/walk.test.ts
@@ -235,44 +235,6 @@ describe('walk', () => {
               "text": "No meta",
             },
           ],
-          "/api": [
-            {
-              "_fileKey": "api/api",
-              "context": undefined,
-              "link": "/api/api",
-              "overviewHeaders": undefined,
-              "tag": undefined,
-              "text": "Api",
-            },
-            {
-              "_fileKey": "api/guide/index",
-              "collapsed": undefined,
-              "collapsible": undefined,
-              "context": undefined,
-              "items": [
-                {
-                  "_fileKey": "api/guide/getting-started",
-                  "context": undefined,
-                  "link": "/api/guide/getting-started",
-                  "overviewHeaders": undefined,
-                  "tag": undefined,
-                  "text": "Getting started",
-                },
-              ],
-              "link": "/api/guide/",
-              "overviewHeaders": undefined,
-              "tag": undefined,
-              "text": "Guide",
-            },
-            {
-              "_fileKey": "api/index",
-              "context": undefined,
-              "link": "/api/",
-              "overviewHeaders": undefined,
-              "tag": undefined,
-              "text": "No meta",
-            },
-          ],
         },
       }
     `);
diff --git a/packages/core/src/node/auto-nav-sidebar/walk.ts b/packages/core/src/node/auto-nav-sidebar/walk.ts
@@ -56,6 +56,18 @@ export async function walk(
     hintNavJsonChangeThenPanic(metaConfig, workDir, docsDir);
   }
 
+  // 0. both `_nav.json` and `_meta.json` exist
+  if (isRootMetaJsonExist && isRootNavJsonExist) {
+    const navConfig = await scanNav(workDir, docsDir);
+    return {
+      nav: navConfig,
+      sidebar: {
+        '/': await scanSideMeta(workDir, docsDir, extensions),
+      },
+    };
+  }
+
+  // 1. only `_nav.json` exist (normal)
   if (isRootNavJsonExist) {
     const navConfig = await scanNav(workDir, docsDir);
     // find the `_meta.json` file in the subdirectory
@@ -87,17 +99,14 @@ export async function walk(
       }),
     );
 
-    if (isRootMetaJsonExist) {
-      const rootMetaConfig = await scanSideMeta(workDir, docsDir, extensions);
-      sidebarConfig['/'] = rootMetaConfig;
-    }
-
     return {
-      nav: navConfig as NavItem[],
+      nav: navConfig,
       sidebar: sidebarConfig,
     };
   }
 
+  // 2. only `_meta.json` exist
+  // 3. both `_nav.json` and `_meta.json` do not exist
   return {
     nav: [],
     sidebar: {

-Original file line number
+Diff line change
@@ @@ -0,0 +1,6 @@ @@
 +[
 +  {
 +    "text": "Guide",
 +    "link": "/guide"
 +  }
 +]
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Feature V1`
	`2`	`+`
	`3`	`+This is a feature of V1.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# 功能 V1`
	`2`	`+`
	`3`	`+这是 V1 的功能。`