feat: add TiDB Cloud Lake namespace and update related mappings and t… (#716)

* feat: add TiDB Cloud Lake namespace and update related mappings and tests

* feat: update TiDB Cloud Lake namespace handling and related tests

Author: shhdgit

gatsby-config.js

@@ -93,7 +93,7 @@ module.exports = {
           {
             matchPath: `/:lang?/(${Object.keys(docs.docs).join(
               "|"
-            )}|developer|best-practices|api|ai|releases)/(.*)`,
+            )}|developer|best-practices|api|ai|releases|tidbcloudlake)/(.*)`,
             getLanguageFromPath: true,
           },
           {

gatsby/URL_MAPPING_ARCHITECTURE.md

@@ -320,7 +320,33 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 8: TiDB Index Pages with Folders
+### Rule 8: TiDB Cloud Lake Namespace
+
+**Effect**: Maps TiDB Cloud Lake pages to the `/tidbcloudlake` namespace.
+
+**Source Pattern**: `/{lang}/tidb-cloud-lake/{branch}/{...folders}/{filename}`
+
+**Target Pattern**:
+- For `_index`: `/{lang}/tidbcloudlake/{folders}` (keeps folder structure)
+- For other files: `/{lang}/tidbcloudlake/{filename}` (flattens folder structure)
+
+**Filename Transform**:
+- `ignoreIf: ["_index"]`
+- `conditionalTarget.keepIf: ["_index"]`
+
+**Example**:
+- Source: `en/tidb-cloud-lake/master/_index.md`
+- Target: `/tidbcloudlake`
+- Source: `en/tidb-cloud-lake/master/tidb-cloud-lake/_index.md`
+- Target: `/tidbcloudlake`
+- Source: `en/tidb-cloud-lake/master/tidb-cloud-lake/guides/dashboards.md`
+- Target: `/tidbcloudlake/dashboards`
+
+**Use Case**: TiDB Cloud Lake content is sourced from its own docs tree but published under a compact top-level namespace.
+
+---
+
+### Rule 9: TiDB Index Pages with Folders
 
 **Effect**: Maps TiDB `_index.md` pages to URLs that keep their folder path, preventing multiple `_index.md` files from collapsing to the same `/tidb/{branch}` URL.
 
@@ -340,7 +366,7 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 9: TiDB with Branch Alias
+### Rule 10: TiDB with Branch Alias
 
 **Effect**: Maps TiDB pages with branch aliasing (master → dev, release-* → v*).
 
@@ -365,7 +391,7 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 10: TiDB-in-Kubernetes with Branch Alias
+### Rule 11: TiDB-in-Kubernetes with Branch Alias
 
 **Effect**: Maps TiDB-in-Kubernetes pages with branch aliasing (main → dev, release-* → v*).
 
@@ -390,7 +416,7 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 11: Fallback Rule
+### Rule 12: Fallback Rule
 
 **Effect**: Generic fallback for any remaining paths.
 
@@ -505,16 +531,17 @@ Rules are evaluated in order; the first matching rule wins.
 
 ### Rule 6: Namespace Index Links (Direct Mapping)
 
-**Effect**: Resolves namespace index links (ending with `/_index`) to namespace URLs (published as `/developer`, `/best-practices`, `/api`, `/ai`, `/tidbcloud`).
+**Effect**: Resolves namespace index links (ending with `/_index`) to namespace URLs (published as `/developer`, `/best-practices`, `/api`, `/ai`, `/tidbcloud`, `/tidbcloudlake`).
 
 **Link Pattern**: `/{namespace}/{...folders}/_index`
 
 **Target Pattern**: `/{curLang}/{namespace}/{folders}`
 
-**Conditions**: `namespace = ["tidb-cloud", "develop", "best-practices", "api", "ai"]`
+**Conditions**: `namespace = ["tidb-cloud", "tidb-cloud-lake", "develop", "best-practices", "api", "ai"]`
 
 **Namespace Transform**:
 - `tidb-cloud` → `tidbcloud`
+- `tidb-cloud-lake` → `tidbcloudlake`
 - `develop` → `developer`
 
 **Example**:
@@ -524,29 +551,36 @@ Rules are evaluated in order; the first matching rule wins.
 - Link: `/best-practices/performance/_index`
 - Current Page: Any page
 - Result: `/best-practices/performance`
+- Link: `/tidb-cloud-lake/_index`
+- Current Page: Any page
+- Result: `/tidbcloudlake`
 
 **Use Case**: Keeps namespace index links consistent with how `_index.md` pages are published.
 
 ---
 
 ### Rule 7: Namespace Links (Direct Mapping)
 
-**Effect**: Resolves namespace links (`develop`, `best-practices`, `api`, `ai`, `tidb-cloud`) to namespace URLs (published as `/developer`, `/best-practices`, `/api`, `/ai`, `/tidbcloud`).
+**Effect**: Resolves namespace links (`develop`, `best-practices`, `api`, `ai`, `tidb-cloud`, `tidb-cloud-lake`) to namespace URLs (published as `/developer`, `/best-practices`, `/api`, `/ai`, `/tidbcloud`, `/tidbcloudlake`).
 
 **Link Pattern**: `/{namespace}/{...any}/{docname}`
 
 **Target Pattern**: `/{curLang}/{namespace}/{docname}`
 
-**Conditions**: `namespace = ["tidb-cloud", "develop", "best-practices", "api", "ai"]`
+**Conditions**: `namespace = ["tidb-cloud", "tidb-cloud-lake", "develop", "best-practices", "api", "ai"]`
 
 **Namespace Transform**:
 - `tidb-cloud` → `tidbcloud`
+- `tidb-cloud-lake` → `tidbcloudlake`
 - `develop` → `developer`
 
 **Example**:
 - Link: `/develop/vector-search`
 - Current Page: Any page
 - Result: `/developer/vector-search`
+- Link: `/tidb-cloud-lake/guides/dashboards`
+- Current Page: Any page
+- Result: `/tidbcloudlake/dashboards`
 
 **Use Case**: Direct links to namespace pages from any location.
 
@@ -574,7 +608,26 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 9: Developer/Best-Practices/API/AI Namespace Page Links (Path-Based)
+### Rule 9: TiDB Cloud Lake Page Links (Path-Based)
+
+**Effect**: Resolves relative links from TiDB Cloud Lake pages to `/tidbcloudlake/*` URLs.
+
+**Path Pattern**: `/{lang}/tidbcloudlake/{...any}`
+
+**Link Pattern**: `/{...any}/{docname}`
+
+**Target Pattern**: `/{lang}/tidbcloudlake/{docname}`
+
+**Example**:
+- Current Page: `/tidbcloudlake`
+- Link: `/guides/dashboards`
+- Result: `/tidbcloudlake/dashboards`
+
+**Use Case**: Relative links within TiDB Cloud Lake documentation preserve the TiDB Cloud Lake namespace.
+
+---
+
+### Rule 10: Developer/Best-Practices/API/AI Namespace Page Links (Path-Based)
 
 **Effect**: Resolves relative links from namespace pages to TiDB stable branch URLs.
 
@@ -598,7 +651,7 @@ Rules are evaluated in order; the first matching rule wins.
 
 ---
 
-### Rule 10: TiDB/TiDB-in-Kubernetes Page Links (Path-Based)
+### Rule 11: TiDB/TiDB-in-Kubernetes Page Links (Path-Based)
 
 **Effect**: Resolves relative links from TiDB or TiDB-in-Kubernetes pages, preserving branch/version.
 
@@ -634,7 +687,7 @@ The URL mapping system provides:
 
 1. **Consistent URL Structure**: Source files are mapped to clean, SEO-friendly URLs
 2. **Context-Aware Link Resolution**: Links are resolved based on the current page's context
-3. **Namespace Support**: Special namespaces (`developer`, `best-practices`, `api`, `ai`) have their own URL structure
+3. **Namespace Support**: Special namespaces (`developer`, `best-practices`, `api`, `ai`, `tidbcloudlake`) have their own URL structure
 4. **Branch Aliasing**: Internal branch names are transformed to user-friendly versions
 5. **Default Language Omission**: Default language (`en`) is omitted from URLs for cleaner paths
 6. **TOC-Driven Build**: Only files referenced in TOC files are built, reducing build size

gatsby/__tests__/get-files-from-tocs.test.ts

@@ -9,6 +9,9 @@ jest.mock("../toc", () => ({
     if (tocSlug.endsWith("/TOC-tidb-cloud-starter")) {
       return [{ type: "nav", link: "/cloud-starter-only.md" }];
     }
+    if (tocSlug.endsWith("/TOC-tidb-cloud-lake")) {
+      return [{ type: "nav", link: "/lake-only.md" }];
+    }
     return [{ type: "nav", link: "/toc-only.md" }];
   }),
 }));
@@ -132,5 +135,30 @@ describe("getFilesFromTocs TOC selection rules", () => {
       new Set(["toc-only", "cloud-starter-only"])
     );
   });
-});
 
+  it("tidb-cloud-lake reads its Lake TOC under master", async () => {
+    const { getFilesFromTocs } = require("../toc-filter");
+
+    const graphql = jest.fn().mockResolvedValue({
+      data: {
+        allMdx: {
+          nodes: [
+            makeNode(
+              "en/tidb-cloud-lake/master/TOC",
+              "docs/markdown-pages/en/tidb-cloud-lake/master/TOC.md"
+            ),
+            makeNode(
+              "en/tidb-cloud-lake/master/TOC-tidb-cloud-lake",
+              "docs/markdown-pages/en/tidb-cloud-lake/master/TOC-tidb-cloud-lake.md"
+            ),
+          ],
+        },
+      },
+    });
+
+    const { tocFilesMap } = await getFilesFromTocs(graphql);
+    expect(new Set(tocFilesMap.get("en/tidb-cloud-lake/master")!)).toEqual(
+      new Set(["toc-only", "lake-only"])
+    );
+  });
+});

gatsby/__tests__/toc-namespace.test.ts

@@ -0,0 +1,28 @@
+import { TOCNamespace } from "../../src/shared/interface";
+import { getTOCNamespace } from "../toc-namespace";
+
+describe("getTOCNamespace", () => {
+  it("maps TiDB Cloud Lake docs to the TiDB Cloud Lake namespace", () => {
+    expect(
+      getTOCNamespace("en/tidb-cloud-lake/master/tidb-cloud-lake/lake-overview")
+    ).toBe(TOCNamespace.TiDBCloudLake);
+  });
+
+  it("maps the TiDB Cloud Lake index page to the TiDB Cloud Lake namespace", () => {
+    expect(
+      getTOCNamespace("en/tidb-cloud-lake/master/tidb-cloud-lake/_index")
+    ).toBe(TOCNamespace.TiDBCloudLake);
+  });
+
+  it("maps root-level TiDB Cloud Lake pages to the TiDB Cloud Lake namespace", () => {
+    expect(getTOCNamespace("en/tidb-cloud-lake/master/_index")).toBe(
+      TOCNamespace.TiDBCloudLake
+    );
+  });
+
+  it("keeps other TiDB stable docs in the TiDB namespace", () => {
+    expect(getTOCNamespace("en/tidb/release-8.5/alert-rules")).toBe(
+      TOCNamespace.TiDB
+    );
+  });
+});

gatsby/link-resolver/__tests__/link-resolver.test.ts

@@ -174,6 +174,14 @@ describe("resolveMarkdownLink", () => {
       expect(result).toBe("/api");
     });
 
+    it("should resolve tidb-cloud-lake/_index links to tidbcloudlake root (en - default language omitted)", () => {
+      const result = resolveMarkdownLink(
+        "/tidb-cloud-lake/_index",
+        "/en/tidb/stable/alert-rules"
+      );
+      expect(result).toBe("/tidbcloudlake");
+    });
+
     it("should resolve best-practices namespace links (en - default language omitted)", () => {
       const result = resolveMarkdownLink(
         "/best-practices/optimization/query-optimization",
@@ -428,6 +436,22 @@ describe("resolveMarkdownLink", () => {
       expect(result).toBe("/zh/tidbcloud/getting-started");
     });
 
+    it("should transform tidb-cloud-lake to tidbcloudlake (en - default language omitted)", () => {
+      const result = resolveMarkdownLink(
+        "/tidb-cloud-lake/guides/dashboards",
+        "/en/tidb/stable/alert-rules"
+      );
+      expect(result).toBe("/tidbcloudlake/dashboards");
+    });
+
+    it("should transform tidb-cloud-lake to tidbcloudlake (zh - language prefix included)", () => {
+      const result = resolveMarkdownLink(
+        "/tidb-cloud-lake/guides/dashboards",
+        "/zh/tidb/stable/alert-rules"
+      );
+      expect(result).toBe("/zh/tidbcloudlake/dashboards");
+    });
+
     it("should not match non-namespace links", () => {
       const result = resolveMarkdownLink(
         "/other/path/to/page",
@@ -493,6 +517,24 @@ describe("resolveMarkdownLink", () => {
     });
   });
 
+  describe("linkMappingsByPath - tidbcloudlake pages", () => {
+    it("should resolve links from tidbcloudlake pages (with lang)", () => {
+      const result = resolveMarkdownLink(
+        "/guides/dashboards",
+        "/en/tidbcloudlake"
+      );
+      expect(result).toBe("/tidbcloudlake/dashboards");
+    });
+
+    it("should resolve links from tidbcloudlake pages (without lang, default omitted)", () => {
+      const result = resolveMarkdownLink(
+        "/guides/dashboards",
+        "/tidbcloudlake"
+      );
+      expect(result).toBe("/tidbcloudlake/dashboards");
+    });
+  });
+
   describe("linkMappingsByPath - tidb pages with branch", () => {
     it("should resolve links from tidb pages with stable branch", () => {
       const result = resolveMarkdownLink(

gatsby/link-resolver/config.ts

@@ -45,27 +45,44 @@ export const defaultLinkResolverConfig: LinkResolverConfig = {
     // /best-practices/_index -> /best-practices
     // /api/_index -> /api
     // /ai/_index -> /ai
+    // /tidb-cloud-lake/_index -> /tidbcloudlake
     {
       linkPattern: "/{namespace}/{...folders}/_index",
       targetPattern: "/{curLang}/{namespace}/{folders}",
       conditions: {
-        namespace: ["tidb-cloud", "develop", "best-practices", "api", "ai"],
+        namespace: [
+          "tidb-cloud",
+          "tidb-cloud-lake",
+          "develop",
+          "best-practices",
+          "api",
+          "ai",
+        ],
       },
       namespaceTransform: {
         "tidb-cloud": "tidbcloud",
+        "tidb-cloud-lake": "tidbcloudlake",
         develop: "developer",
       },
     },
     // /{namespace}/{...any}/{docname} -> /{curLang}/{namespace}/{docname}
-    // Special: tidb-cloud -> tidbcloud, develop -> developer
+    // Special: tidb-cloud -> tidbcloud, tidb-cloud-lake -> tidbcloudlake, develop -> developer
     {
       linkPattern: "/{namespace}/{...any}/{docname}",
       targetPattern: "/{curLang}/{namespace}/{docname}",
       conditions: {
-        namespace: ["tidb-cloud", "develop", "best-practices", "api", "ai"],
+        namespace: [
+          "tidb-cloud",
+          "tidb-cloud-lake",
+          "develop",
+          "best-practices",
+          "api",
+          "ai",
+        ],
       },
       namespaceTransform: {
         "tidb-cloud": "tidbcloud",
+        "tidb-cloud-lake": "tidbcloudlake",
         develop: "developer",
       },
     },
@@ -77,7 +94,15 @@ export const defaultLinkResolverConfig: LinkResolverConfig = {
       linkPattern: "/{...any}/{docname}",
       targetPattern: "/{lang}/tidbcloud/{docname}",
     },
-    // Rule 3: developer, best-practices, api, ai namespace in tidb folder
+    // Rule 3: tidbcloudlake pages (path-based mapping)
+    // Current page: /{lang}/tidbcloudlake/{...any}
+    // Link: /{...any}/{docname} -> /{lang}/tidbcloudlake/{docname}
+    {
+      pathPattern: "/{lang}/tidbcloudlake/{...any}",
+      linkPattern: "/{...any}/{docname}",
+      targetPattern: "/{lang}/tidbcloudlake/{docname}",
+    },
+    // Rule 4: developer, best-practices, api, ai namespace in tidb folder
     // Current page: /{lang}/{namespace}/{...any}
     // Link: /{...any}/{docname} -> /{lang}/{namespace}/{docname}
     {

gatsby/path/index.ts

@@ -96,6 +96,7 @@ function branchToVersion(repo: Repo, branch: string) {
       return branch.replace("release-", "v");
 
     case Repo.tidbcloud:
+    case Repo.tidbcloudlake:
       return null;
   }
 }

gatsby/toc-namespace/index.ts

@@ -72,6 +72,10 @@ const SHARED_NAMESPACE_RULES: NamespaceRule[] = [
     folder: "releases",
     minRestLength: 1,
   },
+  {
+    namespace: TOCNamespace.TiDBCloudLake,
+    repo: Repo.tidbcloudlake,
+  },
   {
     namespace: TOCNamespace.TiDB,
     repo: Repo.tidb,