move setting pageMap items' title property from normalizePages …

…to `sortFolder` (#4166) * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd * upd snapshots
shuding · Feb 6, 2025 · 7949e28 · 7949e28
1 parent b46d831
commit 7949e28
Show file tree

Hide file tree

Showing 27 changed files with 371 additions and 95 deletions.
diff --git a/.changeset/three-monkeys-happen.md b/.changeset/three-monkeys-happen.md
@@ -0,0 +1,5 @@
+---
+"nextra": patch
+---
+
+move setting `pageMap` items' `title` property from `normalizePages` to `sortFolder`
diff --git a/docs/app/docs/built-ins/table/page.mdx b/docs/app/docs/built-ins/table/page.mdx
@@ -5,7 +5,7 @@ icon: TableIcon
 
 import { Table } from 'nextra/components'
 
-# Table Component
+# `<Table>` Component
 
 A collection of built-in components designed to create styled, non-markdown
 (i.e., literal) HTML tables.

diff --git a/docs/app/docs/custom-theme/page.mdx b/docs/app/docs/custom-theme/page.mdx
@@ -2,7 +2,7 @@ import { ExampleCode } from 'components/example-code'
 import { Steps } from 'nextra/components'
 import OldDocs from './old.mdx'
 
-# Custom theme
+# Custom Theme
 
 A theme in Nextra works like a layout, that will be rendered as a wrapper for
 all pages. This docs will walk you through the process of creating a custom

diff --git a/docs/app/docs/docs-theme/built-ins/footer/page.mdx b/docs/app/docs/docs-theme/built-ins/footer/page.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Footer
 
 import { ToggleVisibilitySection } from 'components/toggle-visibility-section'
 
-# `Footer` Component
+# `<Footer>` Component
 
 The footer area of the website. You can specify content for your default footer.
 

diff --git a/docs/app/docs/docs-theme/built-ins/layout/page.mdx b/docs/app/docs/docs-theme/built-ins/layout/page.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Layout
 
 import { ToggleVisibilitySection } from 'components/toggle-visibility-section'
 
-# `Layout` Component
+# `<Layout>` Component
 
 The theme is configured with the `<Layout>` component. You should pass your
 config options as Layout's `props`, for example:

diff --git a/docs/app/docs/docs-theme/built-ins/navbar/page.mdx b/docs/app/docs/docs-theme/built-ins/navbar/page.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Navbar
 
 import { ToggleVisibilitySection } from 'components/toggle-visibility-section'
 
-# `Navbar` Component
+# `<Navbar>` Component
 
 |               |                          |                                         |                                                                                        |
 | ------------- | ------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------- |

diff --git a/docs/app/docs/docs-theme/built-ins/not-found/page.mdx b/docs/app/docs/docs-theme/built-ins/not-found/page.mdx
@@ -2,7 +2,7 @@
 sidebarTitle: NotFoundPage
 ---
 
-# `NotFoundPage` Component
+# `<NotFoundPage>` Component
 
 Options to configure report of broken link on not found page.
 

diff --git a/docs/app/docs/file-conventions/meta-file/page.mdx b/docs/app/docs/file-conventions/meta-file/page.mdx
@@ -80,23 +80,43 @@ The generated `pageMap` will be:
 [
   // content/_meta.js
   { "data": {} },
-  // content/index.mdx
-  { "name": "index", "route": "/", "frontMatter": {} },
-  // content/contact.md
-  { "name": "contact", "route": "/contact", "frontMatter": {} },
+  {
+    // content/index.mdx
+    "name": "index",
+    "route": "/",
+    "title": "Index",
+    "frontMatter": {}
+  },
+  {
+    // content/contact.md
+    "name": "contact",
+    "route": "/contact",
+    "title": "Contact",
+    "frontMatter": {}
+  },
   {
     // content/about
     "name": "about",
     "route": "/about",
+    "title": "About",
     "children": [
       // content/about/_meta.js
       { "data": {} },
-      // content/about/index.mdx
-      { "name": "index", "route": "/about", "frontMatter": {} },
-      // content/about/legal.md
-      { "name": "legal", "route": "/about/legal", "frontMatter": {} }
-    ],
-    "title": "About"
+      {
+        // content/about/index.mdx
+        "name": "index",
+        "route": "/about",
+        "title": "Index",
+        "frontMatter": {}
+      },
+      {
+        // content/about/legal.md
+        "name": "legal",
+        "route": "/about/legal",
+        "title": "Legal",
+        "frontMatter": {}
+      }
+    ]
   }
 ]
 ```

diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
@@ -92,14 +92,15 @@ const footer = (
 const RootLayout: FC<{
   children: ReactNode
 }> = async ({ children }) => {
+  const pageMap = await getPageMap()
   return (
     <html lang="en" dir="ltr" suppressHydrationWarning>
       <Head />
       <body>
         <Layout
           banner={banner}
           navbar={navbar}
-          pageMap={await getPageMap()}
+          pageMap={pageMap}
           docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
           editLink="Edit this page on GitHub"
           sidebar={{ defaultMenuCollapseLevel: 1 }}

diff --git a/packages/nextra-theme-docs/src/components/navbar/index.client.tsx b/packages/nextra-theme-docs/src/components/navbar/index.client.tsx
@@ -124,7 +124,7 @@ export const ClientNavbar: FC<{
           return (
             <Anchor
               href={href}
-              key={href}
+              key={page.name}
               className={cn(
                 classes.link,
                 'x:aria-[current]:font-medium x:aria-[current]:subpixel-antialiased x:aria-[current]:text-current'

diff --git a/packages/nextra/src/client/normalize-pages.ts b/packages/nextra/src/client/normalize-pages.ts
@@ -161,17 +161,10 @@ export function normalizePages({
         pageThemeContext: extendedPageThemeContext
       })
 
-    const title =
-      extendedMeta.title ||
-      currentItem.frontMatter?.sidebarTitle ||
-      currentItem.frontMatter?.title ||
-      // @ts-expect-error -- we use title for capitalize folders without index page
-      (type === 'separator' ? '' : currentItem.title || currentItem.name)
-
     const getItem = (): Item => ({
       ...currentItem,
       type,
-      title,
+      ...('title' in currentItem && { title: currentItem.title }),
       ...(display && { display }),
       ...(normalizedChildren && { children: [] })
     })

diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/page-map.ts b/packages/nextra/src/server/__tests__/fixture/page-maps/page-map.ts
@@ -1,6 +1,14 @@
 import type { PageMapItem } from '../../../../types.js'
 
 export const usPageMap: PageMapItem[] = [
+  {
+    data: {
+      index: 'Introduction',
+      docs: 'Docs',
+      examples: 'Examples',
+      blog: 'Blog'
+    }
+  },
   {
     name: 'blog',
     children: [
@@ -25,20 +33,41 @@ export const usPageMap: PageMapItem[] = [
   {
     name: 'docs',
     children: [
+      {
+        data: {
+          'getting-started': 'Getting Started',
+          options: 'Options',
+          'global-configuration': 'Global Configuration',
+          'data-fetching': 'Data Fetching',
+          'error-handling': 'Error Handling',
+          revalidation: 'Auto Revalidation',
+          'conditional-fetching': 'Conditional Data Fetching',
+          arguments: 'Arguments',
+          mutation: 'Mutation',
+          pagination: 'Pagination',
+          prefetching: 'Prefetching',
+          'with-nextjs': 'Next.js SSG and SSR',
+          typescript: 'Typescript',
+          suspense: 'Suspense',
+          middleware: 'Middleware',
+          advanced: 'Advanced',
+          'change-log': 'Change Log'
+        }
+      },
       {
         name: 'advanced',
         children: [
-          {
-            name: 'cache',
-            route: '/docs/advanced/cache'
-          },
           {
             data: {
               cache: 'Cache',
               performance: 'Performance',
               'react-native': 'React Native'
             }
           },
+          {
+            name: 'cache',
+            route: '/docs/advanced/cache'
+          },
           {
             name: 'performance',
             route: '/docs/advanced/performance'
@@ -78,27 +107,6 @@ export const usPageMap: PageMapItem[] = [
         name: 'global-configuration',
         route: '/docs/global-configuration'
       },
-      {
-        data: {
-          'getting-started': 'Getting Started',
-          options: 'Options',
-          'global-configuration': 'Global Configuration',
-          'data-fetching': 'Data Fetching',
-          'error-handling': 'Error Handling',
-          revalidation: 'Auto Revalidation',
-          'conditional-fetching': 'Conditional Data Fetching',
-          arguments: 'Arguments',
-          mutation: 'Mutation',
-          pagination: 'Pagination',
-          prefetching: 'Prefetching',
-          'with-nextjs': 'Next.js SSG and SSR',
-          typescript: 'Typescript',
-          suspense: 'Suspense',
-          middleware: 'Middleware',
-          advanced: 'Advanced',
-          'change-log': 'Change Log'
-        }
-      },
       {
         name: 'middleware',
         route: '/docs/middleware'
@@ -141,6 +149,15 @@ export const usPageMap: PageMapItem[] = [
   {
     name: 'examples',
     children: [
+      {
+        data: {
+          basic: 'Basic Usage',
+          auth: 'Authentication',
+          'infinite-loading': 'Infinite Loading',
+          'error-handling': 'Error Handling',
+          ssr: 'Next.js SSR'
+        }
+      },
       {
         name: 'auth',
         route: '/examples/auth',
@@ -169,15 +186,6 @@ export const usPageMap: PageMapItem[] = [
           title: 'Infinite Loading'
         }
       },
-      {
-        data: {
-          basic: 'Basic Usage',
-          auth: 'Authentication',
-          'infinite-loading': 'Infinite Loading',
-          'error-handling': 'Error Handling',
-          ssr: 'Next.js SSR'
-        }
-      },
       {
         name: 'ssr',
         route: '/examples/ssr',
@@ -194,13 +202,5 @@ export const usPageMap: PageMapItem[] = [
     frontMatter: {
       title: 'React Hooks for Data Fetching'
     }
-  },
-  {
-    data: {
-      index: 'Introduction',
-      docs: 'Docs',
-      examples: 'Examples',
-      blog: 'Blog'
-    }
   }
 ]
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/1-meta.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/1-meta.mdx
@@ -0,0 +1,4 @@
+export const metadata = {
+  sidebarTitle: 'from sidebarTitle',
+  title: 'from title'
+}
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/2-sidebar-title.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/2-sidebar-title.mdx
@@ -0,0 +1,4 @@
+export const metadata = {
+  sidebarTitle: 'from sidebarTitle',
+  title: 'from title'
+}
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/3-title.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/3-title.mdx
@@ -0,0 +1,3 @@
+export const metadata = {
+  title: 'from title'
+}
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/4-from-filename.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/4-from-filename.mdx
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/_meta.ts b/packages/nextra/src/server/__tests__/fixture/page-maps/title/_meta.ts
@@ -0,0 +1,15 @@
+export default {
+  _: {
+    type: 'separator'
+  },
+  folder: 'from meta',
+  'folder-with-index': '',
+  '1-meta': 'from meta',
+  '2-sidebar-title': '',
+  '3-title': '',
+  '4-from-filename': '',
+  _2: {
+    type: 'separator',
+    title: 'separator with title'
+  }
+}
diff --git a/...s/nextra/src/server/__tests__/fixture/page-maps/title/folder-with-index/foo.mdx b/...s/nextra/src/server/__tests__/fixture/page-maps/title/folder-with-index/foo.mdx
diff --git a/...nextra/src/server/__tests__/fixture/page-maps/title/folder-with-index/index.mdx b/...nextra/src/server/__tests__/fixture/page-maps/title/folder-with-index/index.mdx
@@ -0,0 +1,5 @@
+export const metadata = {
+  asIndexPage: true,
+  sidebarTitle: 'from sidebarTitle',
+  title: 'from title'
+}
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/folder/bar.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/folder/bar.mdx
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/folder/index.mdx b/packages/nextra/src/server/__tests__/fixture/page-maps/title/folder/index.mdx
diff --git a/packages/nextra/src/server/__tests__/fixture/page-maps/title/generated-page-map.ts b/packages/nextra/src/server/__tests__/fixture/page-maps/title/generated-page-map.ts
@@ -0,0 +1,67 @@
+// @ts-nocheck
+import { normalizePageMap } from 'nextra/page-map'
+
+import meta from "./_meta.ts";
+import {metadata as _1_meta} from "./1-meta.mdx?metadata";
+import {metadata as _2_sidebar_title} from "./2-sidebar-title.mdx?metadata";
+import {metadata as _3_title} from "./3-title.mdx?metadata";
+import {metadata as _4_from_filename} from "./4-from-filename.mdx?metadata";
+import {metadata as folder_with_index_foo} from "./folder-with-index/foo.mdx?metadata";
+import {metadata as folder_with_index_index} from "./folder-with-index/index.mdx?metadata";
+import {metadata as folder_bar} from "./folder/bar.mdx?metadata";
+import {metadata as folder_index} from "./folder/index.mdx?metadata";
+
+export const pageMap = normalizePageMap([{
+  data: meta
+}, {
+  name: "1-meta",
+  route: "/1-meta",
+  frontMatter: _1_meta
+}, {
+  name: "2-sidebar-title",
+  route: "/2-sidebar-title",
+  frontMatter: _2_sidebar_title
+}, {
+  name: "3-title",
+  route: "/3-title",
+  frontMatter: _3_title
+}, {
+  name: "4-from-filename",
+  route: "/4-from-filename",
+  frontMatter: _4_from_filename
+}, {
+  name: "folder-with-index",
+  route: "/folder-with-index",
+  children: [{
+    name: "foo",
+    route: "/folder-with-index/foo",
+    frontMatter: folder_with_index_foo
+  }, {
+    name: "index",
+    route: "/folder-with-index",
+    frontMatter: folder_with_index_index
+  }]
+}, {
+  name: "folder",
+  route: "/folder",
+  children: [{
+    name: "bar",
+    route: "/folder/bar",
+    frontMatter: folder_bar
+  }, {
+    name: "index",
+    route: "/folder",
+    frontMatter: folder_index
+  }]
+}])
+
+export const RouteToFilepath = {
+  "1-meta": "1-meta.mdx",
+  "2-sidebar-title": "2-sidebar-title.mdx",
+  "3-title": "3-title.mdx",
+  "4-from-filename": "4-from-filename.mdx",
+  "folder-with-index/foo": "folder-with-index/foo.mdx",
+  "folder-with-index": "folder-with-index/index.mdx",
+  "folder/bar": "folder/bar.mdx",
+  "folder": "folder/index.mdx"
+}