Nextra

https://nextra.site/docs
Admin
missing description
Tokens:55,456
Snippets:501
Trust Score:9.1
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install Pagefind with bun

Source: https://nextra.site/docs/guide/search

Install Pagefind as a dev dependency using bun.

```bash
bun add --dev pagefind
```

--------------------------------

### Install dependencies with npm

Source: https://nextra.site/docs/docs-theme/start

Run this command in your project directory to install Next.js, React, Nextra, and Nextra Docs Theme. If Next.js is already installed, only install nextra and nextra-theme-docs.

```bash
npm i next react react-dom nextra nextra-theme-docs
```

--------------------------------

### Install dependencies with npm

Source: https://nextra.site/docs/blog-theme/start

Installs Next.js, React, Nextra, and the blog theme. If Next.js is already installed, only nextra and nextra-theme-blog are needed.

```bash
npm i next react react-dom nextra nextra-theme-blog
```

--------------------------------

### Build and start production server with npm

Source: https://nextra.site/docs/blog-theme/start

Builds the Next.js application and starts the production server using npm.

```bash
npm run build
npm run start
```

--------------------------------

### styles.css - Global stylesheet example

Source: https://nextra.site/docs/guide/custom-css

Example stylesheet named styles.css that sets body font, padding, max-width, and margin. Use this as a starting point for global styles.

```css
body {
  font-family:
    'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica', 'Arial',
    sans-serif;
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}
```

--------------------------------

### Build and start production server with bun

Source: https://nextra.site/docs/blog-theme/start

Builds the Next.js application and starts the production server using bun.

```bash
bun run build
bun run start
```

--------------------------------

### Install dependencies with bun

Source: https://nextra.site/docs/blog-theme/start

Installs Next.js, React, Nextra, and the blog theme using bun.

```bash
bun add next react react-dom nextra nextra-theme-blog
```

--------------------------------

### Install katex package with bun

Source: https://nextra.site/docs/advanced/latex

Install the `katex` package using bun. This is the first step to apply KaTeX styles.

```bash
bun add katex
```

--------------------------------

### Build and start production server with pnpm

Source: https://nextra.site/docs/blog-theme/start

Builds the Next.js application and starts the production server using pnpm.

```bash
pnpm run build
pnpm run start
```

--------------------------------

### Install Pagefind with pnpm

Source: https://nextra.site/docs/guide/search

Install Pagefind as a dev dependency using pnpm.

```bash
pnpm add -D pagefind
```

--------------------------------

### Install Pagefind with npm

Source: https://nextra.site/docs/guide/search

Install Pagefind as a dev dependency using npm.

```bash
npm i -D pagefind
```

--------------------------------

### Build and start production server with yarn

Source: https://nextra.site/docs/blog-theme/start

Builds the Next.js application and starts the production server using yarn.

```bash
yarn build
yarn run start
```

--------------------------------

### MDX Example for Static Rendering

Source: https://nextra.site/docs/guide/ssg

This MDX code demonstrates how to fetch data at build time using async components and functions. It uses the GitHub API to get star count and last update date, then displays them in a Callout. The data is fetched once at build time and cached.

```MDX
{/* Via async components */}
export async function Stars() {
  const response = await fetch('https://api.github.com/repos/shuding/nextra')
  const repo = await response.json()
  const stars = repo.stargazers_count
  return <b>{stars}</b>
}
 
{/* Via async functions */}
export async function getUpdatedAt() {
  const response = await fetch('https://api.github.com/repos/shuding/nextra')
  const repo = await response.json()
  const updatedAt = repo.updated_at
  return new Date(updatedAt).toLocaleDateString()
}
 
<Callout emoji="🏆">
  Nextra has <Stars /> stars on GitHub!
 
  Last repository update _{await getUpdatedAt()}_.
</Callout>
```

--------------------------------

### Install dependencies with bun

Source: https://nextra.site/docs/docs-theme/start

Alternative package manager command to install the same dependencies.

```bash
bun add next react react-dom nextra nextra-theme-docs
```

--------------------------------

### Install Pagefind with yarn

Source: https://nextra.site/docs/guide/search

Install Pagefind as a dev dependency using yarn.

```bash
yarn add --dev pagefind
```

--------------------------------

### Install katex package with yarn

Source: https://nextra.site/docs/advanced/latex

Install the `katex` package using yarn. This is the first step to apply KaTeX styles.

```bash
yarn add katex
```

--------------------------------

### Install dependencies with pnpm

Source: https://nextra.site/docs/blog-theme/start

Installs Next.js, React, Nextra, and the blog theme using pnpm.

```bash
pnpm add next react react-dom nextra nextra-theme-blog
```

--------------------------------

### Run development server with bun

Source: https://nextra.site/docs/blog-theme/start

Starts the Next.js development server using bun.

```bash
bun run dev
```

--------------------------------

### Run development server with npm

Source: https://nextra.site/docs/blog-theme/start

Starts the Next.js development server using npm.

```bash
npm run dev
```

--------------------------------

### Install katex package with npm

Source: https://nextra.site/docs/advanced/latex

Install the `katex` package using npm. This is the first step to apply KaTeX styles.

```bash
npm i katex
```

--------------------------------

### Install dependencies with pnpm

Source: https://nextra.site/docs/docs-theme/start

Alternative package manager command to install the same dependencies.

```bash
pnpm add next react react-dom nextra nextra-theme-docs
```

--------------------------------

### Install katex package with pnpm

Source: https://nextra.site/docs/advanced/latex

Install the `katex` package using pnpm. This is the first step to apply KaTeX styles.

```bash
pnpm add katex
```

--------------------------------

### Install dependencies with yarn

Source: https://nextra.site/docs/blog-theme/start

Installs Next.js, React, Nextra, and the blog theme using yarn.

```bash
yarn add next react react-dom nextra nextra-theme-blog
```

--------------------------------

### Install dependencies with yarn

Source: https://nextra.site/docs/docs-theme/start

Alternative package manager command to install the same dependencies.

```bash
yarn add next react react-dom nextra nextra-theme-docs
```

--------------------------------

### Install TypeScript and types packages with bun

Source: https://nextra.site/docs/advanced/typescript

Install TypeScript and React/Node type definitions as devDependencies using bun.

```bash
bun add --dev typescript @types/react @types/node
```

--------------------------------

### Run development server with pnpm

Source: https://nextra.site/docs/blog-theme/start

Starts the Next.js development server using pnpm.

```bash
pnpm run dev
```

--------------------------------

### Example _meta.js with numeric keys

Source: https://nextra.site/docs/file-conventions/meta-file

Shows an example _meta file with numeric keys. Note that numbers are always ordered first in JavaScript objects, so keys should be strings.

```javascript
export default {
  foo: '',
  1992_10_21: '',
  1: ''
}
```

--------------------------------

### Install @inkeep/cxkit-react with npm, pnpm, yarn, or bun

Source: https://nextra.site/docs/guide/search/ai

Install the Inkeep React component library using your preferred package manager. The commands are equivalent alternatives.

```bash
npm i @inkeep/cxkit-react
```

```bash
pnpm add @inkeep/cxkit-react
```

```bash
yarn add @inkeep/cxkit-react
```

```bash
bun add @inkeep/cxkit-react
```

--------------------------------

### Run development server with yarn

Source: https://nextra.site/docs/blog-theme/start

Starts the Next.js development server using yarn.

```bash
yarn dev
```

--------------------------------

### Install TypeScript and types packages with pnpm

Source: https://nextra.site/docs/advanced/typescript

Install TypeScript and React/Node type definitions as devDependencies using pnpm.

```bash
pnpm add -D typescript @types/react @types/node
```

--------------------------------

### Top-level _meta.js example

Source: https://nextra.site/docs/file-conventions/meta-file

Example of a top-level _meta.js file that defines meta information for top-level pages and folders.

```javascript
export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  fruits: 'Delicious Fruits',
  about: 'About Us'
}
```

--------------------------------

### Install TypeScript and types packages with npm

Source: https://nextra.site/docs/advanced/typescript

Install TypeScript and React/Node type definitions as devDependencies using npm.

```bash
npm i -D typescript @types/react @types/node
```

--------------------------------

### Install TypeScript and types packages with yarn

Source: https://nextra.site/docs/advanced/typescript

Install TypeScript and React/Node type definitions as devDependencies using yarn.

```bash
yarn add --dev typescript @types/react @types/node
```

--------------------------------

### _meta.js with fallback '*' key

Source: https://nextra.site/docs/file-conventions/meta-file

Example _meta.js file that uses the '*' key to define fallback configuration for all items in the folder.

```javascript
export default {
  '*': {
    type: 'page'
  },
  index: 'Home',
  frameworks: 'Frameworks',
  fruits: 'Fruits',
  about: 'About'
}
```

--------------------------------

### Nested fruits/_meta.js example

Source: https://nextra.site/docs/file-conventions/meta-file

Example of a nested _meta.js file for the fruits folder, defining meta for apple and banana pages.

```javascript
export default {
  apple: 'Apple',
  banana: 'Banana'
}
```

--------------------------------

### MDX example with React component

Source: https://nextra.site/docs/guide/markdown

Shows how to import and use React components inside an MDX file. The example defines a Counter component using useState and renders it with children and count.

```mdx
## Hello MDX
 
import { useState } from 'react'
 
export function Counter({ children }) {
  const [count, setCount] = useState(0)
  return (
    <button onClick={() => setCount(prev => prev + 1)}>
      {children}
      {count}
    </button>
  )
}
 
<Counter>**Clicks**: </Counter>
```

--------------------------------

### _meta.js with menu

Source: https://nextra.site/docs/file-conventions/meta-file

Example _meta.js file that adds a menu to the navbar using type: 'menu' and items.

```javascript
export default {
  company: {
    title: 'Company',
    type: 'menu',
    items: {
      about: {
        title: 'About',
        href: '/about'
      },
      contact: {
        title: 'Contact Us',
        href: 'mailto:hi@example.com'
      }
    }
  }
}
```

--------------------------------

### Converted _meta.js with string keys

Source: https://nextra.site/docs/file-conventions/meta-file

Shows how the previous example is converted: numeric keys become strings and are ordered first. This demonstrates why keys should be strings.

```javascript
export default {
  '1': '',
  '19921021': '',
  foo: ''
}
```

--------------------------------

### Footer Component Usage

Source: https://nextra.site/docs/docs-theme/built-ins/footer

Example showing how to use the Footer component by passing children, such as copyright information.

```APIDOC
## Footer Component

### Description
Use the Footer component to specify content for the default footer of your website. You can add content, such as copyright information, by passing it as children.

### Props
- `...props` (DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>) - Optional - Additional HTML attributes for the footer element.

### Example
```jsx
import { Footer, Layout } from 'nextra-theme-docs'
 
export default function MyLayout({ children, ...props }) {
  return (
    <Layout>
      {children}
      <Footer>
        MIT {new Date().getFullYear()} ©{' '}
        <a href="https://nextra.site" target="_blank">
          Nextra
        </a>
        .
      </Footer>
      {children}
    </Layout>
  )
}
```

### Toggle Visibility
You can toggle visibility of the `<Footer>` on specific pages by setting the `theme.footer` property in the `_meta.js` file.

```js
export default {
  'my-page': {
    theme: {
      footer: false // Hide footer on this page
    }
  }
}
```
```

--------------------------------

### Front matter for index page with asIndexPage

Source: https://nextra.site/docs/file-conventions/meta-file

Front matter example for an index page (content/fruits/index.mdx or app/fruits/page.mdx) that sets asIndexPage: true to create a folder with an index page.

```markdown
---
title: All Fruits
sidebarTitle: 🍒 Fruits
asIndexPage: true
---
```

--------------------------------

### Highlighting substrings with // attribute

Source: https://nextra.site/docs/guide/syntax-highlighting

Shows how to highlight specific substrings of code by adding a // attribute with a regex pattern. The example highlights all occurrences of 'useState'.

```markdown
```js /useState/
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```
```

--------------------------------

### MDXRemote usage example

Source: https://nextra.site/docs/built-ins/mdxremote

Example of using MDXRemote with compileMdx. The compiledSource prop receives the result of compileMdx, components maps custom component names to React components, and scope provides variables accessible in the MDX content.

```jsx
import { compileMdx } from 'nextra/compile'
import { MDXRemote } from 'nextra/mdx-remote'
 
<MDXRemote
  compiledSource={await compileMdx('# Hello {myVariable} <MyComponent />')}
  components={{ MyComponent: () => <div>My Component</div> }}
  scope={{ myVariable: 'World' }}
/>
```

--------------------------------

### Add postbuild script for server builds

Source: https://nextra.site/docs/guide/search

Add a postbuild script to package.json for server builds, indexing .next/server/app and outputting to public/_pagefind.

```json
"scripts": {
  "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind"
}
```

--------------------------------

### Create /rss.xml route with GET handler

Source: https://nextra.site/docs/blog-theme/rss

Use this snippet to create an RSS feed route in a Next.js app. It imports getPosts, defines a CONFIG object with site metadata, and exports a GET function that returns an RSS 2.0 XML response. The response includes a Content-Type header of application/rss+xml.

```javascript
import { getPosts } from '../posts/get-posts.js'
 
const CONFIG = {
  title: 'My Blog',
  siteUrl: 'https://your-domain.com',
  description: 'Latest blog posts',
  lang: 'en-us'
}
 
export async function GET() {
  const allPosts = await getPosts()
  const posts = allPosts
    .map(
      post => `    <item>
        <title>${post.title}</title>
        <description>${post.frontMatter.description}</description>
        <link>${CONFIG.siteUrl}${post.route}</link>
        <pubDate>${new Date(post.frontMatter.date).toUTCString()}</pubDate>
    </item>`
    )
    .join('\n')
  const xml = `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <title>${CONFIG.title}</title>
    <link>${CONFIG.siteUrl}</link>
    <description>${CONFIG.description}</description>
    <language>${CONFIG.lang}</language>
${posts}
  </channel>
</rss>`
 
  return new Response(xml, {
    headers: {
      'Content-Type': 'application/rss+xml'
    }
  })
}
```

--------------------------------

### Create content/index.mdx

Source: https://nextra.site/docs/file-conventions/content-directory

Create this file as your first MDX page. It contains a simple heading and paragraph.

```markdown
# Welcome to Nextra
 
Hello, world!
```

--------------------------------

### Usage: Import and render Table with subcomponents

Source: https://nextra.site/docs/built-ins/table

Shows how to import Table from 'nextra/components' and use Table.Tr, Table.Th, and Table.Td to build a table. The example creates a table with a header row and two data rows.

```jsx
import { Table } from 'nextra/components'
 
<Table>
  <thead>
    <Table.Tr>
      <Table.Th>Country</Table.Th>
      <Table.Th>Flag</Table.Th>
    </Table.Tr>
  </thead>
  <tbody>
    <Table.Tr>
      <Table.Td>France</Table.Td>
      <Table.Td>🇫🇷</Table.Td>
    </Table.Tr>
    <Table.Tr>
      <Table.Td>Ukraine</Table.Td>
      <Table.Td>🇺🇦</Table.Td>
    </Table.Tr>
  </tbody>
</Table>
```

--------------------------------

### Add scripts to package.json

Source: https://nextra.site/docs/blog-theme/start

Adds the standard Next.js scripts for development, building, and starting the production server.

```json
"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
},
```

--------------------------------

### Example npm2yarn code block with npm, pnpm, yarn, and bun commands

Source: https://nextra.site/docs/advanced/npm2yarn

Shows the four package manager commands that appear as tabs when using npm2yarn. The chosen tab is saved in local storage for future page renders.

```bash
npm i -D @graphql-eslint/eslint-plugin
```

```bash
pnpm add -D @graphql-eslint/eslint-plugin
```

```bash
yarn add --dev @graphql-eslint/eslint-plugin
```

```bash
bun add --dev @graphql-eslint/eslint-plugin
```

--------------------------------

### _meta.js with external link

Source: https://nextra.site/docs/file-conventions/meta-file

Example _meta.js file that adds an external link item with href to the sidebar.

```javascript
export default {
  github_link: {
    title: 'Nextra',
    href: 'https://github.com/shuding/nextra'
  }
}
```

--------------------------------

### Build commands for npm, pnpm, yarn, and bun

Source: https://nextra.site/docs/guide/static-exports

Run the build command using your preferred package manager. The static export will be stored in the 'out' directory by default.

```bash
npm run build
```

```bash
pnpm run build
```

```bash
yarn build
```

```bash
bun run build
```

--------------------------------

### Update postbuild script in package.json for Pagefind

Source: https://nextra.site/docs/guide/static-exports

Set the postbuild script to run pagefind with the correct output path. This is required for the Pagefind search engine setup to work with static exports.

```json
"scripts": {
  "postbuild": "pagefind --site .next/server/app --output-path out/_pagefind"
}
```

--------------------------------

### _meta.js with separator

Source: https://nextra.site/docs/file-conventions/meta-file

Example _meta.js file that uses a placeholder item with type: 'separator' to create a separator line.

```javascript
export default {
  '###': {
    type: 'separator',
    title: 'My Items' // Title is optional
  }
}
```

--------------------------------

### Inlined syntax highlighting with {:} syntax

Source: https://nextra.site/docs/guide/syntax-highlighting

Shows how to use the {:} syntax to apply inlined syntax highlighting to a code span in Markdown. The example highlights 'let x = 1' as JSX.

```markdown
Inlined syntax highlighting is also supported `let x = 1{:jsx}` via:
```

--------------------------------

### Table Component Usage

Source: https://nextra.site/docs/built-ins/table

Example of using the Table component with its sub-components to create a table with a header and body rows.

```APIDOC
## Table Component

### Description
The Table component is used to create styled, non-markdown HTML tables. It accepts standard HTML table attributes and provides sub-components for rows and cells.

### Props
- `...props` (HTMLAttributes<HTMLTableElement>) - Optional - Standard HTML table attributes.

### Usage Example
```jsx
import { Table } from 'nextra/components'
 
<Table>
  <thead>
    <Table.Tr>
      <Table.Th>Country</Table.Th>
      <Table.Th>Flag</Table.Th>
    </Table.Tr>
  </thead>
  <tbody>
    <Table.Tr>
      <Table.Td>France</Table.Td>
      <Table.Td>🇫🇷</Table.Td>
    </Table.Tr>
    <Table.Tr>
      <Table.Td>Ukraine</Table.Td>
      <Table.Td>🇺🇦</Table.Td>
    </Table.Tr>
  </tbody>
</Table>
```
```

--------------------------------

### next.config.js with unsupported plugins

Source: https://nextra.site/docs/guide/turbopack

Example of passing remark, rehype, and recma plugins to the nextra function. These are functions and are not serializable, so they cannot be used with Turbopack.

```javascript
import nextra from 'nextra'
 
const withNextra = nextra({
  mdxOptions: {
    remarkPlugins: [myRemarkPlugin],
    rehypePlugins: [myRehypePlugin],
    recmaPlugins: [myRecmaPlugin]
  }
})
```

--------------------------------

### FileTree Component Usage

Source: https://nextra.site/docs/built-ins/filetree

Example of using the FileTree component with nested Folder and File components to create a file tree structure.

```APIDOC
## FileTree Component

### Description
A built-in component to visually represent a file tree. Exported from `nextra/components`.

### Props
- `...props` (HTMLAttributes<HTMLUListElement>) - Default: - - Additional HTML attributes for the underlying `<ul>` element.

### Usage
Create the file tree structure by nesting `<FileTree.Folder>` and `<FileTree.File>` components within a `<FileTree>`. Name each file or folder with the `name` attribute. Use `defaultOpen` to set the folder to open on load.

### Example
```mdx
import { FileTree } from 'nextra/components'
 
<FileTree>
  <FileTree.Folder name="content" defaultOpen>
    <FileTree.File name="_meta.js" />
    <FileTree.File name="contact.md" />
    <FileTree.File name="index.mdx" />
    <FileTree.Folder name="about">
      <FileTree.File name="_meta.js" />
      <FileTree.File name="legal.md" />
      <FileTree.File name="index.mdx" />
    </FileTree.Folder>
  </FileTree.Folder>
</FileTree>
```
```

--------------------------------

### Create root layout app/layout.jsx

Source: https://nextra.site/docs/docs-theme/start

Create this file inside the app folder to configure your Nextra Theme. It imports components from nextra-theme-docs and nextra/components, and sets up the layout with banner, navbar, pageMap, docsRepositoryBase, and footer.

```jsx
import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}
```

--------------------------------

### Theme configuration with DocsThemeConfig type

Source: https://nextra.site/docs/advanced/typescript

Example theme.config.tsx file that imports the DocsThemeConfig type from nextra-theme-docs and uses it to type the configuration object.

```tsx
import type { DocsThemeConfig } from 'nextra-theme-docs'
 
const config: DocsThemeConfig = {
  // Your theme configuration
}
export default config
```

--------------------------------

### Create root layout in app/layout.jsx

Source: https://nextra.site/docs/blog-theme/start

Defines the root layout for the blog theme, including banner, navbar, search, theme switch, and footer. Uses nextra-theme-blog components and imports the theme CSS.

```jsx
import { Footer, Layout, Navbar, ThemeSwitch } from 'nextra-theme-blog'
import { Banner, Head, Search } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-blog/style.css'
 
export const metadata = {
  title: 'Blog Example'
}
 
export default async function RootLayout({ children }) {
  const banner = (
    <Banner storageKey="4.0-release">
      🎉 Nextra 4.0 is released.{' '}
      <a
        href="#"
        style={{
          textDecoration: 'underline',
          textUnderlinePosition: 'from-font'
        }}
      >
        Read more →
      </a>
    </Banner>
  )
 
  return (
    <html lang="en" suppressHydrationWarning>
      <Head backgroundColor={{ dark: '#0f172a', light: '#fefce8' }} />
      <body>
        <Layout banner={banner}>
          <Navbar pageMap={await getPageMap()}>
            <Search />
            <ThemeSwitch />
          </Navbar>
 
          {children}
 
          <Footer>
            <abbr
              title="This site and all its content are licensed under a Creative Commons Attribution-NonCommercial 4.0 International License."
              style={{ cursor: 'help' }}
            >
              CC BY-NC 4.0
            </abbr>{' '}
            {new Date().getFullYear()} © Dimitri POSTOLOV.
            <a href="/feed.xml" style={{ float: 'right' }}>
              RSS
            </a>
          </Footer>
        </Layout>
      </body>
    </html>
  )
}
```
Tokens:
Raw