{:js}`, `| {:js}` and ` | {:js}` – your
+table will be unstyled because
+[MDX](https://mdxjs.com/docs/using-mdx/#components) doesn't replace literal HTML
+elements with components provided by `useMDXComponents(){:js}`[^1].
+
+> [!TIP]
+>
+> Instead, use the [built-in `` component](/docs/guide/built-ins/table)
+> available via `nextra/components`.
+
+## Changing default behaviour
+
+If you want to use standard HTML elements for your tables but have them styled
+with components provided by `useMDXComponents(){:js}`[^1], you can do this by
+configuring Nextra.
+
+To achieve this, pass the `whiteListTagsStyling` option to the Nextra function,
+including an array of tags you want to replace.
+
+Here's an example configuration in your `next.config.mjs` file:
+
+```js filename="next.config.mjs" {4}
+import nextra from 'nextra'
+
+const withNextra = nextra({
+ whiteListTagsStyling: ['table', 'thead', 'tbody', 'tr', 'th', 'td']
+})
+
+export default withNextra()
+```
+
+In this example, the tags ``, ``, ``, ``, `| `, and
+` | ` will be replaced with corresponding MDX components, allowing for
+customized styling.
+
+[^1]: https://mdxjs.com/packages/react/#usemdxcomponentscomponents
diff --git a/docs/app/docs/advanced/tailwind-css/page.mdx b/docs/app/docs/advanced/tailwind-css/page.mdx
new file mode 100644
index 0000000000..7782e40ca2
--- /dev/null
+++ b/docs/app/docs/advanced/tailwind-css/page.mdx
@@ -0,0 +1,72 @@
+---
+icon: TailwindIcon
+---
+
+import { Steps } from 'nextra/components'
+
+# Tailwind CSS
+
+Tailwind CSS is a CSS framework that provides a set of pre-defined CSS classes
+to quickly style elements. You can follow the official
+[Tailwind CSS documentation for Next.js](https://tailwindcss.com/docs/guides/nextjs)
+to set up Tailwind CSS for your Nextra project.
+
+
+
+## Create `tailwind.config.js` file
+
+To use Tailwind classes in your Markdown files, you will also need to add `.md`
+and `.mdx` files to the `content` list in `tailwind.config.js`:
+
+```js filename="tailwind.config.js" /md,mdx/
+/** @type {import('tailwindcss').Config} */
+export default {
+ content: [
+ './app/**/*.{js,jsx,ts,tsx,md,mdx}',
+ './content/**/*.{md,mdx}',
+
+ // Or if using `src` directory:
+ './src/**/*.{js,jsx,ts,tsx,md,mdx}'
+ ],
+ theme: {
+ extend: {}
+ },
+ plugins: []
+}
+```
+
+> [!TIP]
+>
+> You can also use a `tailwind.config.ts` file if you prefer TypeScript for your
+> Tailwind CSS configuration.
+
+## Create the `globals.css` file
+
+Create a CSS file for Tailwind directives, `globals.css` for example:
+
+```css filename="globals.css"
+@tailwind base; /* Apply Tailwind's base styles (Preflight) */
+@tailwind components; /* Include component styles */
+@tailwind utilities; /* Include utility classes */
+```
+
+> [!NOTE]
+>
+> If you're using `nextra-theme-docs` or `nextra-theme-blog`, you don't need to
+> include the `@tailwind base` directive. These themes already import Tailwind's
+> preflight styles in their `style.css` files.
+
+## Import styles in the root layout
+
+To apply the styles globally, import the `globals.css` file in your root layout
+file:
+
+```jsx filename="app/layout.jsx"
+import '../path/to/your/globals.css'
+
+export default async function RootLayout({ children }) {
+ // ... Your layout logic here
+}
+```
+
+
diff --git a/docs/app/docs/advanced/twoslash/page.mdx b/docs/app/docs/advanced/twoslash/page.mdx
new file mode 100644
index 0000000000..d156329e8e
--- /dev/null
+++ b/docs/app/docs/advanced/twoslash/page.mdx
@@ -0,0 +1,74 @@
+# Twoslash Support
+
+Twoslash provides an inline type hove inside the code block.
+
+## Basic usage
+
+You can enable twoslash to your code blocks by adding a `twoslash` metadata:
+
+{/* prettier-ignore */}
+````md copy=false filename="Markdown"
+```ts twoslash
+// @errors: 2540
+interface Todo {
+ title: string
+}
+
+const todo: Readonly = {
+ title: 'Delete inactive users'.toUpperCase()
+ // ^?
+}
+
+todo.title = 'Hello'
+
+Number.parseInt('123', 10)
+// ^|
+ // Just comments, so Popup will be
+ // not behind the viewport of ``
+ // element due his `position: absolute` style
+ //
+```
+````
+
+Renders:
+
+{/* prettier-ignore */}
+```ts twoslash
+// @errors: 2540
+interface Todo {
+ title: string
+}
+
+const todo: Readonly = {
+ title: 'Delete inactive users'.toUpperCase()
+ // ^?
+}
+
+todo.title = 'Hello'
+
+Number.parseInt('123', 10)
+// ^|
+
+
+
+
+```
+
+## Custom log message
+
+You can add log message to your code by adding:
+
+- `@log: ` Custom log message
+- `@error: ` Custom error message
+- `@warn: ` Custom warn message
+- `@annotate: ` Custom annotate message
+
+```ts twoslash
+// @log: Custom log message
+const a = 1
+// @error: Custom error message
+const b = 1
+// @warn: Custom warning message
+const c = 1
+// @annotate: Custom annotation message
+```
diff --git a/docs/app/docs/advanced/typescript/page.mdx b/docs/app/docs/advanced/typescript/page.mdx
new file mode 100644
index 0000000000..d2f44f3642
--- /dev/null
+++ b/docs/app/docs/advanced/typescript/page.mdx
@@ -0,0 +1,50 @@
+---
+icon: TypeScriptIcon
+---
+
+import { Steps } from 'nextra/components'
+
+# TypeScript
+
+Nextra is built with TypeScript and provides excellent TypeScript support out of
+the box. This guide will help you leverage TypeScript in your Nextra project.
+
+## Getting started
+
+To use TypeScript in your Nextra project, you need to:
+
+
+### Install TypeScript and types packages as `devDependencies`
+
+```sh npm2yarn
+npm i -D typescript @types/react @types/node
+```
+
+### `tsconfig.json`
+
+You can manually create a `tsconfig.json` file in the root of your project or
+rename the extension of some of the existing files to `.ts` or `.tsx` and then
+Next.js will detect TypeScript in your project and create a `tsconfig.json` file
+for you.
+
+
+
+## Type definitions
+
+Nextra provides type definitions for distribution code for its components and
+configurations. You can leverage these types by renaming your theme
+configuration file to `.ts` or `.tsx` extension and importing a theme config
+type, e.g. for `nextra-theme-docs`:
+
+```tsx filename="theme.config.tsx"
+import type { DocsThemeConfig } from 'nextra-theme-docs'
+
+const config: DocsThemeConfig = {
+ // Your theme configuration
+}
+export default config
+```
+
+By leveraging TypeScript in your Nextra project, you can catch errors early,
+improve code quality, and enhance the developer experience with better
+autocompletion and type inference.
diff --git a/docs/app/docs/blog-theme/get-posts-and-tags/page.mdx b/docs/app/docs/blog-theme/get-posts-and-tags/page.mdx
new file mode 100644
index 0000000000..8792165737
--- /dev/null
+++ b/docs/app/docs/blog-theme/get-posts-and-tags/page.mdx
@@ -0,0 +1,16 @@
+---
+icon: FilesIcon
+---
+
+import { ExampleCode } from 'components/example-code'
+
+# Get Posts and Their Tags
+
+The following code snippet demonstrates how to retrieve all posts along with
+their associated tags.
+
+
diff --git a/docs/app/docs/blog-theme/page.mdx b/docs/app/docs/blog-theme/page.mdx
new file mode 100644
index 0000000000..d72cfd712d
--- /dev/null
+++ b/docs/app/docs/blog-theme/page.mdx
@@ -0,0 +1,29 @@
+---
+asIndexPage: true
+sidebarTitle: Blog Theme
+---
+
+import {
+ ChevronRightIcon,
+ FilesIcon,
+ RSSIcon,
+ TagsIcon
+} from '@components/icons'
+import { Cards } from 'nextra/components'
+import { FileIcon } from 'nextra/icons'
+import { MDXRemote } from 'nextra/mdx-remote'
+import { createIndexPage, getPageMap } from 'nextra/page-map'
+
+# Nextra Blog Theme
+
+
diff --git a/docs/app/docs/blog-theme/posts/page.mdx b/docs/app/docs/blog-theme/posts/page.mdx
new file mode 100644
index 0000000000..00b1eea18f
--- /dev/null
+++ b/docs/app/docs/blog-theme/posts/page.mdx
@@ -0,0 +1,15 @@
+---
+icon: FileIcon
+---
+
+import { ExampleCode } from 'components/example-code'
+
+# Posts Page
+
+The following code snippet demonstrates how to create `/posts` page.
+
+
diff --git a/docs/app/docs/blog-theme/rss/page.mdx b/docs/app/docs/blog-theme/rss/page.mdx
new file mode 100644
index 0000000000..3fba006151
--- /dev/null
+++ b/docs/app/docs/blog-theme/rss/page.mdx
@@ -0,0 +1,15 @@
+---
+icon: RSSIcon
+---
+
+import { ExampleCode } from 'components/example-code'
+
+# Generate RSS feed
+
+The following code snippet demonstrates how to create `/rss.xml` route.
+
+
diff --git a/docs/app/docs/blog-theme/start/page.mdx b/docs/app/docs/blog-theme/start/page.mdx
new file mode 100644
index 0000000000..a8e8a3f2f4
--- /dev/null
+++ b/docs/app/docs/blog-theme/start/page.mdx
@@ -0,0 +1,81 @@
+---
+icon: ChevronRightIcon
+---
+
+import InstallNextraTheme from '@components/install-nextra-theme.mdx'
+import ReadyToGo from '@components/ready-to-go.mdx'
+import { ExampleCode } from '@components/example-code'
+import { Steps } from 'nextra/components'
+
+# Get Started
+
+> [!NOTE]
+>
+> An example of the blog theme can be found [here](https://demo.vercel.blog),
+> with source code [here](https://github.com/vercel/nextjs-portfolio-starter).
+
+Similar to the [Docs Theme](/docs/docs-theme/start), you can install the blog
+theme with the following commands:
+
+## Start as a new project
+
+
+### Install
+
+To create a Nextra Blog site manually, you have to install **Next.js**,
+**React**, **Nextra**, and **Nextra Blog Theme**. In your project directory, run
+the following command to install the dependencies:
+
+```sh npm2yarn
+npm i next react react-dom nextra nextra-theme-blog
+```
+
+> [!NOTE]
+>
+> If you already have Next.js installed in your project, you only need to
+> install `nextra` and `nextra-theme-blog` as the add-ons.
+
+
+
+### Add [`mdx-components` file](/docs/file-conventions/mdx-components-file)
+
+### Create root layout
+
+
+
+{/*
+
+### Create Blog Theme Config
+
+Lastly, create the corresponding `theme.config.jsx` file in your project's root
+directory. This will be used to configure the Nextra Blog theme:
+
+```jsx filename="theme.config.jsx"
+export default {
+ footer: MIT 2023 © Nextra. ,
+ head: ({ title, meta }) => (
+ <>
+ {meta.description && (
+
+ )}
+ {meta.tag && }
+ {meta.author && }
+
+ ),
+ readMore: 'Read More →',
+ postFooter: null,
+ darkMode: false,
+ navs: [
+ {
+ url: 'https://github.com/shuding/nextra',
+ name: 'Nextra'
+ }
+ ]
+}
+```
+
+*/}
+
+
+
+
diff --git a/docs/app/docs/blog-theme/tags/page.mdx b/docs/app/docs/blog-theme/tags/page.mdx
new file mode 100644
index 0000000000..d4deea57e6
--- /dev/null
+++ b/docs/app/docs/blog-theme/tags/page.mdx
@@ -0,0 +1,15 @@
+---
+icon: TagsIcon
+---
+
+import { ExampleCode } from 'components/example-code'
+
+# Tags Page
+
+The following code snippet demonstrates how to create `/tags/:id` pages.
+
+
diff --git a/docs/app/docs/built-ins/banner/page.mdx b/docs/app/docs/built-ins/banner/page.mdx
new file mode 100644
index 0000000000..62e1fe8b68
--- /dev/null
+++ b/docs/app/docs/built-ins/banner/page.mdx
@@ -0,0 +1,44 @@
+---
+sidebarTitle: Banner
+---
+
+# `` Component
+
+Show a banner on the top of the website. It can be used to show a warning or a
+notice.
+
+| | | | |
+| ------------- | ---------------- | ---------------------- | ------------------------------------- |
+| `dismissible` | `boolean{:ts}` | `true` | Closable banner or not. |
+| `key` | `string{:ts}` | `'nextra-banner'{:ts}` | Storage key to keep the banner state. |
+| `children` | `ReactNode{:ts}` | | Content of the banner. |
+
+## Banner key
+
+A banner can be dismissed. By default, it's used by
+[localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
+to keep the banner state on the client.
+
+If you have updated your banner text, you should change the key to make sure the
+banner is shown again. The best practice is to always use a descriptive key for
+the current text, for example:
+
+
+
+```jsx filename="app/layout.jsx" {7-11}
+import { Layout } from 'my-nextra-theme'
+import { Banner } from 'nextra/components'
+
+export default function MyLayout({ children, ...props }) {
+ return (
+
+
+
+ 🎉 Nextra 2.0 is released. Read more →
+
+
+ {children}
+
+ )
+}
+```
diff --git a/docs/app/docs/built-ins/bleed/page.mdx b/docs/app/docs/built-ins/bleed/page.mdx
new file mode 100644
index 0000000000..9ea738cecf
--- /dev/null
+++ b/docs/app/docs/built-ins/bleed/page.mdx
@@ -0,0 +1,58 @@
+---
+sidebarTitle: Bleed
+---
+
+import { Bleed } from 'nextra/components'
+
+# `` Component
+
+## Example
+
+When wrapping your content with ``, it will be slightly wider than the
+container and will overflow on both sides.
+
+
+
+ _There is nothing to writing. All you do is sit down at a typewriter and **bleed**._
+
+ — Ernest Hemingway
+
+
+
+
+It provides a better reading experience when you want to present some graphical
+information, which normally looks nicer in a larger size.
+
+For example, you can put text, image, video or any component inside:
+
+
+
+
+
+You can even make it full-bleed using ``:
+
+
+
+## Usage
+
+```mdx filename="MDX"
+import { Bleed } from 'nextra/components'
+
+Hey, I can use **Markdown** syntax here.
+
+
+
+
+
+
+```
diff --git a/docs/app/docs/built-ins/callout/page.mdx b/docs/app/docs/built-ins/callout/page.mdx
new file mode 100644
index 0000000000..61f9ff54b5
--- /dev/null
+++ b/docs/app/docs/built-ins/callout/page.mdx
@@ -0,0 +1,120 @@
+---
+sidebarTitle: Callout
+icon: WarningIcon
+---
+
+import { useMDXComponents } from 'next-mdx-import-source-file'
+import { Callout } from 'nextra/components'
+import { InformationCircleIcon } from 'nextra/icons'
+
+# `` Component
+
+A built-in component to show important information to the reader.
+
+## Example
+
+
+ A **callout** is a short piece of text intended to attract attention.
+
+
+
+ A **callout** is a short piece of text intended to attract attention.
+
+
+
+ A **callout** is a short piece of text intended to attract attention.
+
+
+
+ A **callout** is a short piece of text intended to attract attention.
+
+
+## Usage
+
+### Default
+
+
+ **Space Invaders** is a 1978 shoot 'em up arcade game developed by Tomohiro
+ Nishikado.
+
+
+```mdx
+import { Callout } from 'nextra/components'
+
+
+ **Space Invaders** is a 1978 shoot 'em up arcade game developed by Tomohiro
+ Nishikado.
+
+```
+
+### Info
+
+
+ Today is Friday.
+
+
+```mdx
+import { Callout } from 'nextra/components'
+
+
+ Today is Friday.
+
+```
+
+### Warning
+
+
+ This API will be deprecated soon.
+
+
+```mdx
+import { Callout } from 'nextra/components'
+
+
+ This API will be deprecated soon.
+
+```
+
+### Error
+
+
+ This is a dangerous feature that can cause everything to explode.
+
+
+```mdx
+import { Callout } from 'nextra/components'
+
+
+ This is a dangerous feature that can cause everything to explode.
+
+```
+
+## API
+
+The callout component takes the following props:
+
+export function Emoji() {
+ const { code: Code } = useMDXComponents()
+ return (
+
+ '💡' for type: 'default'
+
+ '🚫' for type: 'error'
+
+ {' '}
+ for type: 'info'
+
+ '⚠️' for type: 'warning'
+
+
+ )
+}
+
+| | | | |
+| ---------- | -------------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `type` | `'default' \| 'info' \| 'warning' \| 'error'{:ts}` | `'default'` | The type of the callout. |
+| `emoji` | `string \| ReactNode{:ts}` | | The icon to show in the callout. You can also render your custom icon. |
+| `children` | `ReactNode{:ts}` | | The content of the callout. |
diff --git a/docs/app/docs/built-ins/cards/page.mdx b/docs/app/docs/built-ins/cards/page.mdx
new file mode 100644
index 0000000000..d552a582e5
--- /dev/null
+++ b/docs/app/docs/built-ins/cards/page.mdx
@@ -0,0 +1,82 @@
+---
+sidebarTitle: Cards
+icon: IdCardIcon
+---
+
+import { CardsIcon, OneIcon, WarningIcon, BoxIcon } from '@components/icons'
+import { compileMdx } from 'nextra/compile'
+import { Cards } from 'nextra/components'
+import { MDXRemote } from 'nextra/mdx-remote'
+
+# `` Component
+
+A built-in component that allows you to display content in a visually appealing card format. It
+includes options for adding an icon, title, link and an image to related content.
+
+export async function CardsPage() {
+ const mdx2 = `}
+ title="About Nextra"
+ href="/about"
+ arrow
+/>`
+ const mdx = `
+
+ }
+ title="Callout"
+ href="/docs/built-ins/callout"
+ />
+ }
+ title="Tabs"
+ href="/docs/built-ins/tabs"
+ />
+ }
+ title="Steps"
+ href="/docs/built-ins/steps"
+ />
+`
+ const rawJs = await compileMdx(`
+## Grouped Cards
+
+### Example
+
+${mdx}
+
+### Usage
+
+Import the \`\` component to your page, which includes the \`\` component.
+
+Then, _optionally_ import the icons that you want to use. To create a set of cards, follow the
+example below where the \`\` component is used to create a card and the \`\`
+component is used to group multiple cards together.
+
+~~~mdx filename="MDX"
+import { Cards } from 'nextra/components'
+import { CardsIcon, OneIcon, WarningIcon } from '../path/with/your/icons'
+${mdx}
+~~~
+
+## Single Card
+
+A \`\` not wrapped in a \`\` component will not be grouped with other cards. This can
+be useful if you want to display a single card in a different format than the other cards on the
+page.
+
+### Example
+
+
+
+${mdx2}
+
+### Usage
+
+~~~mdx filename="MDX"
+${mdx2}
+~~~`)
+ return
+}
+
+
diff --git a/docs/app/docs/built-ins/filetree/page.mdx b/docs/app/docs/built-ins/filetree/page.mdx
new file mode 100644
index 0000000000..c18f7d829e
--- /dev/null
+++ b/docs/app/docs/built-ins/filetree/page.mdx
@@ -0,0 +1,50 @@
+---
+sidebarTitle: FileTree
+icon: FolderTreeIcon
+---
+
+import { FileTree } from 'nextra/components'
+
+# `` Component
+
+A built-in component to visually represent a file tree.
+
+## Example
+
+Click the folder to test the dynamic functionality of the file tree.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Usage
+
+Create the file tree structure by nesting `` and
+`` components within a ``. Name each file or folder
+with the `name` attribute. Use `defaultOpen` to set the folder to open on load.
+
+```mdx filename="MDX"
+import { FileTree } from 'nextra/components'
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
diff --git a/docs/app/docs/built-ins/head/_slider.tsx b/docs/app/docs/built-ins/head/_slider.tsx
new file mode 100644
index 0000000000..f2fad2811a
--- /dev/null
+++ b/docs/app/docs/built-ins/head/_slider.tsx
@@ -0,0 +1,72 @@
+'use client'
+
+import type { ComponentProps, FC } from 'react'
+import { useCallback, useEffect, useState } from 'react'
+
+export const Slider: FC = ({
+ cssVar,
+ max
+}: {
+ cssVar: string
+ max: number
+}) => {
+ const handleChange: NonNullable['onChange']> =
+ useCallback(
+ e => {
+ const value = `${e.target.value}${max === 360 ? 'deg' : '%'}`
+ e.target.nextSibling!.textContent = value
+ document.documentElement.style.setProperty(cssVar, value)
+ },
+ [cssVar, max]
+ )
+
+ return (
+
+
+
+
+ )
+}
+
+function hexToRgb(hex: `#${string}`): string {
+ const bigint = Number.parseInt(hex.slice(1), 16)
+ const r = (bigint >> 16) & 255
+ const g = (bigint >> 8) & 255
+ const b = bigint & 255
+ return `${r},${g},${b}`
+}
+
+export const BackgroundColor: FC = () => {
+ const [value, setValue] = useState('')
+ useEffect(() => {
+ const color = getComputedStyle(document.body).getPropertyValue(
+ '--nextra-bg'
+ )
+ setValue(color)
+ }, [])
+
+ return (
+
+ {
+ const { value } = e.target
+ e.target.nextSibling!.textContent = value
+ document.documentElement.style.setProperty(
+ '--nextra-bg',
+ hexToRgb(value as `#${string}`)
+ )
+ }}
+ />
+
+
+ )
+}
diff --git a/docs/app/docs/built-ins/head/page.mdx b/docs/app/docs/built-ins/head/page.mdx
new file mode 100644
index 0000000000..8b3baf1188
--- /dev/null
+++ b/docs/app/docs/built-ins/head/page.mdx
@@ -0,0 +1,124 @@
+---
+sidebarTitle: Head
+---
+
+import { BackgroundColor, Slider } from './_slider'
+
+# `` Component
+
+Configure the `` tags, primary color, background color and favicon glyph
+of the website.
+
+| | | | |
+| ----------------------- | ------------------------------------------------ | -------------------------------- | ---------------------------------------------------- |
+| `children` | `ReactNode{:ts}` | | Content of ``. |
+| `color.hue` | `number \| { dark: number; light: number }{:ts}` | `{ dark: 204, light: 212 }{:ts}` | The hue of the primary theme color. (0 - 360) |
+| `color.saturation` | `number \| { dark: number; light: number }{:ts}` | `100{:ts}` | The saturation of the primary theme color. (0 - 100) |
+| `color.lightness` | `number \| { dark: number; light: number }` | `{ dark: 55, light: 45 }{:ts}` | The lightness of the primary theme color. (0 - 100) |
+| `backgroundColor.dark` | `"rgb(RRR,GGG,BBB)" \| "#RRGGBB"{:ts}` | `'rgb(17,17,17)'{:ts}` | Background color for light theme. |
+| `backgroundColor.light` | `"rgb(RRR,GGG,BBB)" \| "#RRGGBB"{:ts}` | `'rgb(250,250,250)'{:ts}` | Background color for dark theme. |
+| `faviconGlyph` | `string{:ts}` | | The glyph to use as the favicon. |
+
+## Static Head Tags
+
+If you have static head tags, they should be put as `children` in `Head`. For
+example:
+
+```jsx filename="app/layout.jsx" {8}
+import { Layout } from 'my-nextra-theme'
+import { Head } from 'nextra/components'
+
+export default function MyLayout({ children, ...props }) {
+ return (
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+## Dynamic Tags Based on Page
+
+You can dynamically generate the head tags based on the current page's front
+matter. For example:
+
+### via Markdown front matter
+
+```mdx filename="my-page/page.mdx"
+---
+title: My title
+description: My description
+---
+```
+
+### via exporting `metadata` object
+
+{/* prettier-ignore */}
+```mdx filename="my-page/page.mdx"
+export const metadata = {
+ title: 'My title',
+ description: 'My description'
+}
+```
+
+### in [dynamic routes with Catch-all segment](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#catch-all-segments)
+
+```jsx filename="app/[[...mdxPath]]/page.jsx"
+import { importPage } from 'nextra/pages'
+
+export async function generateMetadata(props) {
+ const { mdxPath } = await props.params
+ const { metadata } = await importPage(mdxPath)
+ return {
+ title: metadata.title || 'Nextra',
+ description: metadata.description || 'The next site builder'
+ }
+}
+```
+
+You can refer to the [`useConfig`](/docs/docs-theme/api) API section for more
+information about the `useConfig` hook and the `frontMatter` object.
+
+## Theme Color
+
+You can adjust the theme color of the website by setting primary Hue, Saturation
+and Lightness (HSL) values for light and dark themes. Try it out for this
+website:
+
+| Hue (H) | Saturation (S) | Lightness (L) | Background Color |
+| -------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------- | ------------------ |
+| | | | |
+
+> [!TIP]
+>
+> You can adjust the lightness independently for dark or light mode to increase
+> legibility. E.g. to have a neutral primary color you can set the primary color
+> to be white `HSL(0, 0%, 100%)` on dark theme and gray `HSL(0, 0%, 50%)` for
+> light theme.
+>
+> ```jsx filename="app/layout.jsx"
+> color={{
+> hue: 0,
+> saturation: 0,
+> lightness: {
+> light: 50,
+> dark: 100
+> }
+> }}
+> />
+> ```
+
+## Favicon Glyph
+
+This isn't supported by all browsers, but it's a nice way to customize the
+favicon of the website simply by using an emoji or character.
+
+```jsx filename="app/layout.jsx"
+
+```
diff --git a/docs/app/docs/built-ins/page.mdx b/docs/app/docs/built-ins/page.mdx
new file mode 100644
index 0000000000..57cc5cac2b
--- /dev/null
+++ b/docs/app/docs/built-ins/page.mdx
@@ -0,0 +1,34 @@
+---
+asIndexPage: true
+sidebarTitle: Built-In Components
+---
+
+import {
+ CardsIcon,
+ FolderTreeIcon,
+ IdCardIcon,
+ OneIcon,
+ TableIcon,
+ WarningIcon
+} from '@components/icons'
+import { Cards } from 'nextra/components'
+import { MDXRemote } from 'nextra/mdx-remote'
+import { createIndexPage, getPageMap } from 'nextra/page-map'
+
+# Built-ins
+
+Nextra includes a couple of built-in components that you can use to better style
+your content:
+
+
diff --git a/docs/app/docs/built-ins/search/page.mdx b/docs/app/docs/built-ins/search/page.mdx
new file mode 100644
index 0000000000..d8b78e8220
--- /dev/null
+++ b/docs/app/docs/built-ins/search/page.mdx
@@ -0,0 +1,14 @@
+---
+sidebarTitle: Search
+---
+
+# `` Component
+
+| | | | |
+| --------------- | ----------------------------- | ------------------------------------- | ------------------------------------------------------------------------------- |
+| `emptyResult` | `string \| ReactElement{:ts}` | `'No results found.'{:ts}` | Not found text. |
+| `loading` | `string \| ReactElement{:ts}` | `'Loading…'{:ts}` | Loading text. |
+| `errorText` | `string \| ReactElement{:ts}` | `'Failed to load search index.'{:ts}` | Error text. |
+| `placeholder` | `string{:ts}` | `'Search documentation…'{:ts}` | Placeholder text. |
+| `className` | `string{:ts}` | | CSS class name. |
+| `searchOptions` | `PagefindSearchOptions{:ts}` | | `{preload?: boolean; verbose?: boolean; filters?: object; sort?: object}{:ts}`. |
diff --git a/docs/app/docs/built-ins/steps/page.mdx b/docs/app/docs/built-ins/steps/page.mdx
new file mode 100644
index 0000000000..3eb3d0ef5a
--- /dev/null
+++ b/docs/app/docs/built-ins/steps/page.mdx
@@ -0,0 +1,70 @@
+---
+sidebarTitle: Steps
+icon: OneIcon
+---
+
+import { Steps } from 'nextra/components'
+
+# `` Component
+
+A built-in component to turn a numbered list into a visual representation of
+steps.
+
+## Example
+
+
+
+### This is the first step
+
+This is the first step description.
+
+### This is the second step
+
+This is the second step description.
+
+### This is the third step
+
+This is the third step description.
+
+
+
+## Usage
+
+Wrap a set of Markdown headings (from `` to ``) with the ``
+component to display them as visual steps. You can choose the appropriate
+heading level based on the content hierarchy on the page.
+
+{/* prettier-ignore */}
+```mdx filename="MDX" {7-15}
+import { Steps } from 'nextra/components'
+
+## Getting Started
+
+Here is some description.
+
+
+### Step 1
+
+Contents for step 1.
+
+### Step 2
+
+Contents for step 2.
+
+```
+
+## Excluding Headings from Table of Contents
+
+To exclude the headings from the `` component (or any other headings) to
+appear in the Table of Contents, replace the Markdown headings `### ...` with
+`` HTML element wrapped in curly braces.
+
+{/* prettier-ignore */}
+```diff filename="MDX"
+
+- ### Step 1
++ {Step 1}
+
+Contents for step 1.
+
+```
diff --git a/docs/app/docs/built-ins/table/page.mdx b/docs/app/docs/built-ins/table/page.mdx
new file mode 100644
index 0000000000..e7a69c493c
--- /dev/null
+++ b/docs/app/docs/built-ins/table/page.mdx
@@ -0,0 +1,57 @@
+---
+sidebarTitle: Table
+icon: TableIcon
+---
+
+import { Table } from 'nextra/components'
+
+# `` Component
+
+A collection of built-in components designed to create styled, non-markdown
+(i.e., literal) HTML tables.
+
+## Example
+
+
+
+
+ Country
+ Flag
+
+
+
+
+ France
+ 🇫🇷
+
+
+ Ukraine
+ 🇺🇦
+
+
+
+
+## Usage
+
+```mdx
+import { Table } from 'nextra/components'
+
+
+
+
+ Country
+ Flag
+
+
+
+
+ France
+ 🇫🇷
+
+
+ Ukraine
+ 🇺🇦
+
+
+
+```
diff --git a/docs/app/docs/built-ins/tabs/page.mdx b/docs/app/docs/built-ins/tabs/page.mdx
new file mode 100644
index 0000000000..42adb12a8a
--- /dev/null
+++ b/docs/app/docs/built-ins/tabs/page.mdx
@@ -0,0 +1,53 @@
+---
+sidebarTitle: Tabs
+icon: CardsIcon
+---
+
+# `` Component
+
+## Example
+
+import { Tabs } from 'nextra/components'
+
+{/* prettier-ignore */}
+
+ **pnpm**: Fast, disk space efficient package manager.
+ **npm** is a package manager for the JavaScript programming language.
+ **Yarn** is a software packaging system.
+
+
+## Usage
+
+### Default
+
+{/* prettier-ignore */}
+```mdx
+import { Tabs } from 'nextra/components'
+
+
+ **pnpm**: Fast, disk space efficient package manager.
+ **npm** is a package manager for the JavaScript programming language.
+ **Yarn** is a software packaging system.
+
+```
+
+### Default Selected Index
+
+You can use the `defaultIndex` prop to set the default tab index:
+
+```mdx /defaultIndex="1"/
+import { Tabs } from 'nextra/components'
+
+
+ ...
+
+```
+
+And you will have `npm` as the default tab:
+
+{/* prettier-ignore */}
+
+ **pnpm**: Fast, disk space efficient package manager.
+ **npm** is a package manager for the JavaScript programming language.
+ **Yarn** is a software packaging system.
+
diff --git a/docs/app/docs/custom-theme/old.mdx b/docs/app/docs/custom-theme/old.mdx
new file mode 100644
index 0000000000..13f8c625f2
--- /dev/null
+++ b/docs/app/docs/custom-theme/old.mdx
@@ -0,0 +1,91 @@
+### Render metadata for the active page
+
+> [!WARNING]
+>
+> Docs from Nextra 3
+
+Other than `children`, some other useful props are passed to the theme layout
+too. With the `pageOpts` props, the theme can access the page's meta
+information.
+
+For example, let's implement these features:
+
+- Render the page title in ``
+- Show a simple Table of Contents via MDX `<Wrapper>` component
+- Add a meta tag for `og:image` via the front matter
+
+```tsx filename="theme.tsx" /pageOpts/
+import Head from 'next/head'
+import type { NextraThemeLayoutProps } from 'nextra'
+import { MDXProvider } from 'nextra/mdx'
+
+export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
+ const { title, frontMatter } = pageOpts
+
+ return (
+ <>
+ <Head>
+ <title>{title}
+
+
+ {children}
+
+ )
+}
+
+function MyWrapper({ children, toc }) {
+ return (
+ <>
+ My Theme
+ Table of Contents:
+
+ {toc.map(heading => (
+ - {heading.value}
+ ))}
+
+ {children}
+
+ )
+}
+```
+
+### Use page map of the entire site
+
+> [!WARNING]
+>
+> Docs from Nextra 3
+
+Now, if you want to render something like a sidebar or a navigation bar, which
+relies on information of not only the current page but also other pages, you can
+use the `pageMap` value.
+
+For example, we can render a simple navigation list with all the pages in the
+top level:
+
+```tsx filename="theme.tsx" /pageMap/
+import Link from 'next/link'
+import type { NextraThemeLayoutProps } from 'nextra'
+
+export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
+ const { pageMap } = pageOpts
+
+ return (
+
+ My Theme
+ {pageMap.map(item => {
+ if ('route' in item && !('children' in item)) {
+ return (
+
+ {item.route}
+
+ )
+ }
+ })}
+ {children}
+
+
+Inside your theme layout, you can use CSS imports or other ways to style it.
+Next.js hooks such as `usePathname` are also available.
+
+{process.env.NODE_ENV !== 'production' && }
+
+
diff --git a/docs/app/docs/docs-theme/api/page.mdx b/docs/app/docs/docs-theme/api/page.mdx
new file mode 100644
index 0000000000..2dd3c3be6f
--- /dev/null
+++ b/docs/app/docs/docs-theme/api/page.mdx
@@ -0,0 +1,28 @@
+# API
+
+## `useThemeConfig` hook
+
+The `useThemeConfig` hook returns values of your
+[theme configuration](/docs/docs-theme/theme-configuration) and is made to
+dynamically configure your project.
+
+```js
+import { useThemeConfig } from 'nextra-theme-docs'
+```
+
+## `useConfig` hook
+
+```js
+import { useConfig } from 'nextra-theme-docs'
+```
+
+The `useConfig` hook returns data from your current page context.
+
+## Return Values
+
+- `hideSidebar`: is sidebar hidden
+- `normalizePagesResult`: `ReturnType{:ts}`
+- `normalizePagesResult.activeMetadata`: parsed
+ [front matter](https://jekyllrb.com/docs/front-matter) or exported
+ [Metadata](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)
+ from page
diff --git a/docs/app/docs/docs-theme/built-ins/footer/page.mdx b/docs/app/docs/docs-theme/built-ins/footer/page.mdx
new file mode 100644
index 0000000000..6fd7b8aaa2
--- /dev/null
+++ b/docs/app/docs/docs-theme/built-ins/footer/page.mdx
@@ -0,0 +1,41 @@
+---
+sidebarTitle: Footer
+---
+
+import { ToggleVisibilitySection } from 'components/toggle-visibility-section'
+
+# ` | |
+
+
+ 
+
+
+ 
+
+