`_meta.js` 文件

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

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

组织文件

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

在 Next.js 的 app 目录中：
Nextra 收集所有 page 文件，包括 page.md 和 page.mdx 文件以及 _meta 文件。
在 Nextra 的 content 目录中：
Nextra 收集所有 .md 和 .mdx 文件，以及 _meta 文件。

以下是 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": "/", "frontMatter": {} },
  // content/contact.md
  { "name": "contact", "route": "/contact", "frontMatter": {} },
  {
    // content/about
    "name": "about",
    "route": "/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"
  }
]

然后，Nextra 会将全局 pageMap 导入到每个页面。然后，配置的主题将使用该 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

Using page.mdx files

- _meta.js
- layout.jsx
- page.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

Using page.mdx files

- _meta.js
- layout.jsx
- page.mdx

_meta.js


export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  about: 'About Us'
}

Note

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


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

`type: 'page'` 选项

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

例如，您可以在项目中拥有 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

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

Option	Type	Default Value	Description
`breadcrumb`	`boolean`	`true`	显示或隐藏面包屑导航。
`collapsed`	`boolean`	`false`	表示侧边栏中的项目是否默认折叠。
`footer`	`boolean`	`true`	指定是否显示页脚。
`layout`	`'default' \| 'full'`	`'default'`	定义布局样式。
`navbar`	`boolean`	`true`	指定是否显示导航栏。
`pagination`	`boolean`	`true`	确定是否显示分页控件。
`sidebar`	`boolean`	`true`	指定是否显示侧边栏。
`timestamp`	`boolean`	`true`	表示是否显示“最后更新”时间戳。
`toc`	`boolean`	`true`	确定是否显示目录。
`typesetting`	`'default' \| 'article'`	`'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` 页面

要创建带有索引页面的文件夹，请在其前言中添加 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' // 标题是可选的
  }
}

菜单

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


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 文件相同，但有一个例外：文件夹项目必须包含 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 文件扩展名。

_meta.js 文件

组织文件

pageMap 结构

API

title 类型

页面

type: 'page' 选项

display: 'hidden' 选项

theme 选项

布局

排版

文件夹

带有 /index 页面

链接

分隔符

菜单

回退

_meta.global 文件

需要了解的内容

排序页面

_meta 键的类型

`_meta.js` 文件

`pageMap` 结构

`title` 类型

`type: 'page'` 选项

`display: 'hidden'` 选项

`theme` 选项

带有 `/index` 页面

`_meta.global` 文件

`_meta` 键的类型