Skip to Content
🎉 Nextra 4.0 已发布。dimaMachina 正在 寻找新工作或咨询机会 。
文档文件约定_meta.js

_meta.js 文件

在 Nextra 中，站点和单个页面结构可以通过同级的 _meta 文件进行配置。这些配置会影响 Nextra 主题的整体布局，特别是导航栏和边栏：

Nextra 主题文档示例
示例：Nextra 文档主题 会从 Markdown 文件自动生成边栏和导航栏。

组织文件

Nextra 允许您以以下方式组织文件：

以下是针对 content 和仅 app 目录的相同基于文件的路由结构表示：

    Using content directory
    • layout.jsx
      • _meta.js
      • index.mdx
      • legal.md
    • _meta.js
    • contact.md
    • index.mdx
    Using page.mdx files
      • _meta.js
      • page.mdx
    • _meta.js
    • layout.jsx
    • page.mdx
Note

您可以为项目结合两种组织方式：

  • 使用 .mdx 文件的 content 目录
  • 使用 page 文件的 app 目录

pageMap 结构

随后，Nextra 会生成一个 pageMap 数组，其中包含有关整个站点路由和目录结构的信息。诸如导航栏和边栏等功能可以基于 pageMap 信息生成。

生成的 pageMap 将是：

pageMap
[
  // content/_meta.js
  { "data": {} },
  {
    // 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",
        "title": "Index",
        "frontMatter": {}
      },
      {
        // content/about/legal.md
        "name": "legal",
        "route": "/about/legal",
        "title": "Legal",
        "frontMatter": {}
      }
    ]
  }
]

全局 pageMap 将被 Nextra 导入到每个页面中。然后，配置的主题将使用该 pageMap 渲染实际的 UI。

API

页面在边栏/导航栏中显示的标题和顺序可以在 _meta 文件中配置为键值对。

_meta.ts
import type { MetaRecord } from 'nextra'
 
/**
 * type MetaRecordValue =
 *  | TitleSchema
 *  | PageItemSchema
 *  | SeparatorSchema
 *  | MenuSchema
 *
 * type MetaRecord = Record<string, MetaRecordValue>
 **/
const meta: MetaRecord = {
  // ...
}
 
export default meta

title 类型

在 _meta 文件中指定 title 时，您可以将其定义为简单的字符串或 JSX 元素。

type TitleSchema = string | ReactElement

对于以下文件结构：

    Using content directory
    • layout.jsx
    • _meta.js
    • about.mdx
    • contact.mdx
    • index.mdx

以下 _meta 文件定义了页面标题：

_meta.jsx
import { GitHubIcon } from 'nextra/icons'
 
export default {
  index: 'My Homepage',
  // You can use JSX elements to change the look of titles in the sidebar, e.g. insert icons
  contact: (
    <Italic className="my-class">
      <GitHubIcon height="20" />
      Contact Us
    </Italic>
  ),
  about: {
    // Alternatively, you can set title with `title` property
    title: 'About Us'
    // ... and provide extra configurations
  }
}
 
// Custom component for italicized text
function Italic({ children, ...props }) {
  return <i {...props}>{children}</i>
}

页面

在 _meta 文件中，您可以定义页面在边栏中的显示方式，例如对于以下文件结构：

    Using content directory
    • layout.jsx
    • _meta.js
    • about.mdx
    • contact.mdx
    • index.mdx
_meta.js
export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  about: 'About Us'
}
Note

如果任何路由未在 _meta 文件中列出，它们将被追加到边栏的末尾，并按字母顺序排序（除了 index 键，如果未在 _meta 文件中指定，它将排在首位）。

type PageItemSchema = {
  type: 'page' | 'doc' // @default 'doc'
  display: 'normal' | 'hidden' | 'children' // @default 'normal'
  title?: TitleSchema
  theme?: PageThemeSchema
}

type: 'page' 选项

通过将顶级页面或文件夹定义为 type: 'page'，它将作为特殊页面显示在导航栏中，而不是边栏。使用此功能，您可以拥有多个“子文档”，以及始终可见的特殊页面或链接，例如“Contact Us”。

例如，您可以在项目中拥有 2 个文档文件夹 frameworks 和 fruits。在顶级 _meta 文件中，您可以将所有内容设置为页面，而不是普通的边栏项：

    Using content directory
    • layout.jsx
      • react.mdx
      • svelte.mdx
      • vue.mdx
      • apple.mdx
      • banana.mdx
    • _meta.js
    • about.mdx
    • index.mdx
    Using page.mdx files
    • _meta.js
    • layout.jsx
    • page.mdx
_meta.js
export default {
  index: {
    title: 'Home',
    type: 'page'
  },
  frameworks: {
    title: 'Frameworks',
    type: 'page'
  },
  fruits: {
    title: 'Fruits',
    type: 'page'
  },
  about: {
    title: 'About',
    type: 'page'
  }
}

它将如下所示：

StackBlitz 上的实时示例 
Tip

您也可以使用 display: 'hidden' 选项从导航栏隐藏诸如 Home 之类的链接。

您可以在导航栏中添加外部链接，类似于 链接部分：

_meta.js
export default {
  contact: {
    title: 'Contact Us',
    type: 'page',
    href: 'https://example.com/contact'
  }
}

display: 'hidden' 选项

默认情况下，文件系统中的所有 MDX 路由都会显示在边栏中。但您可以使用 display: 'hidden' 配置隐藏特定页面或文件夹：

_meta.js
export default {
  contact: {
    display: 'hidden'
  }
}
Note

该页面仍然可以通过 /contact URL 访问，但不会显示在边栏中。

theme 选项

您可以使用 theme 选项为每个页面配置主题。例如，您可以为特定页面禁用或启用特定组件：

_meta.js
export default {
  about: {
    theme: {
      sidebar: false
    }
  }
}
Warning

如果为文件夹设置此选项，它将被所有子页面继承。

NameTypeDefault
collapsedboolean

Indicates whether the item in sidebar is collapsed by default.

false
copyPageboolean

Specifies whether to display the copy page button.

true
layout"default,full"

Defines the layout style.

'default'
paginationboolean

Determines if pagination controls are shown.

true
timestampboolean

Indicates if “last updated” timestamps are displayed.

true
tocboolean

Determines whether a table of contents is displayed.

true
typesetting"default,article"

Configures the text typesetting style.

'default'
布局

默认情况下，每个页面的主题配置中都有 layout: 'default'，这是默认行为。您可能希望以全容器宽度和高度渲染某些页面，但保留所有其他样式。您可以使用 'full' 布局来实现：

_meta.js
export default {
  about: {
    theme: {
      layout: 'full'
    }
  }
}
排版

typesetting 选项控制排版细节，如字体特性、标题样式以及 <li> 和 <code> 等组件。在文档主题中，有 'default' 和 'article' 两种排版可用。

默认排版适合大多数情况，如文档，但您可以使用 'article' 排版使其看起来像优雅的文章页面：

_meta.js
export default {
  about: {
    theme: {
      typesetting: 'article'
    }
  }
}
StackBlitz 上的实时示例 

文件夹

文件夹可以以与页面相同的方式配置。

例如，以下顶级 _meta 文件包含顶级页面和文件夹的元信息。
嵌套的 _meta 文件包含同一文件夹中页面的元信息：

    Using content directory
    • layout.jsx
      • _meta.js
      • apple.mdx
      • banana.mdx
    • _meta.js
    • about.mdx
    • contact.mdx
    • index.mdx
    Using page.mdx files
      • _meta.js
    • _meta.js
    • layout.jsx
    • page.mdx
_meta.js
export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  fruits: 'Delicious Fruits',
  about: 'About Us'
}
fruits/_meta.js
export default {
  apple: 'Apple',
  banana: 'Banana'
}
Note

您可以移动目录而无需更改 _meta 文件，因为页面信息在目录中分组在一起。

带有 /index 页面的文件夹

要创建带有索引页面的文件夹，请在其 frontmatter 中添加 asIndexPage: true。

例如，要创建 /fruits 路由，设置 asIndexPage: true 会告诉 Nextra /fruits 是一个带有索引页面的文件夹。在边栏中点击文件夹将展开它并显示 MDX 页面。

    Using content directory
    • layout.jsx
      • _meta.js
      • apple.mdx
      • banana.mdx
      • index.mdx
    • _meta.js
    • about.mdx
    • contact.mdx
    • index.mdx
    Using page.mdx files
      • _meta.js
      • page.mdx
    • _meta.js
    • layout.jsx
    • page.mdx
content/fruits/index.mdx or app/fruits/page.mdx
---
title: All Fruits
sidebarTitle: 🍒 Fruits
asIndexPage: true
---

链接

type LinkSchema = {
  href: string
  title?: TitleSchema
}

您可以通过在 _meta 文件中添加带有 href 的项，将外部链接添加到边栏：

_meta.js
export default {
  github_link: {
    title: 'Nextra',
    href: 'https://github.com/shuding/nextra'
  }
}
Tip

您也可以使用此选项链接到相对内部链接。

分隔符

type SeparatorSchema = {
  type: 'separator'
  title?: TitleSchema
}

您可以使用带有 type: 'separator' 的“占位符”项，在边栏中的项之间创建分隔线：

_meta.js
export default {
  '###': {
    type: 'separator',
    title: 'My Items' // Title is optional
  }
}

菜单

您也可以使用 type: 'menu' 和 items 选项将菜单添加到导航栏：

导航栏菜单
StackBlitz 上的实时示例 
type MenuItemSchema =
  | TitleSchema
  | { title: TitleSchema }
  | (LinkSchema & { type?: 'page' | 'doc' })
  | SeparatorSchema
 
type MenuSchema = {
  type: 'menu'
  title?: TitleSchema
  items: Record<string, MenuItemSchema>
}
_meta.js
export default {
  company: {
    title: 'Company',
    type: 'menu',
    items: {
      about: {
        title: 'About',
        href: '/about'
      },
      contact: {
        title: 'Contact Us',
        href: 'mailto:hi@example.com'
      }
    }
  }
}

回退

在上文的 type: 'page' 选项 中，我们必须为每个页面定义 type: 'page' 选项。为了简化，您可以使用 '*' 键为该文件夹中的所有项定义回退配置：

_meta.js
export default {
  '*': {
    type: 'page'
  },
  index: 'Home',
  frameworks: 'Frameworks',
  fruits: 'Fruits',
  about: 'About'
}

它们相当于所有项都设置了 type: 'page'。

_meta.global 文件

您也可以在单个 _meta 文件中定义所有页面，该文件以 .global 结尾。API 与文件夹特定的 _meta 文件相同，有 1 个例外：文件夹项必须包含 items 字段。

对于以下结构，您可能使用以下 _meta 文件：

    Using content directory
    • layout.jsx
      • _meta.js
      • apple.mdx
      • banana.mdx
    • _meta.js
    • index.mdx
    Using page.mdx files
      • _meta.js
    • _meta.js
    • layout.jsx
    • page.mdx
_meta.js
export default {
  fruits: {
    type: 'page',
    title: '✨ Fruits'
  }
}
fruits/_meta.js
export default {
  apple: '🍎 Apple',
  banana: '🍌 BaNaNa'
}

使用单个 _meta.global 文件，可以如下定义：

_meta.global.js
export default {
  fruits: {
    type: 'page',
    title: '✨ Fruits',
    items: {
      apple: '🍎 Apple',
      banana: '🍌 BaNaNa'
    }
  }
}
Warning

您不能在项目中使用 _meta.global 和 _meta 文件两者。

好记

排序页面

您可以使用 ESLint 的内置 sort-keys 规则，在 _meta 文件顶部添加 /* eslint sort-keys: error */ 注释，您将收到有关顺序错误的 ESLint 错误。

_meta 键的类型

您的 _meta 键的类型始终应该是字符串而不是数字，因为 数字总是在 JavaScript 对象中排在首位 。

例如，考虑以下内容：

_meta.js
export default {
  foo: '',
  1992_10_21: '',
  1: ''
}

将被转换为：

_meta.js
export default {
  '1': '',
  '19921021': '',
  foo: ''
}
Tip

_meta 文件可以使用 .js、.jsx 或 .tsx 文件扩展名。

Last updated on
page.mdxmdx-components.js