Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra builds a page map at compile time — a tree of PageMapItem nodes that describes every MDX file, folder, and _meta configuration in your content directory. The nextra/page-map module exposes functions to retrieve this tree at request time, transform it for custom navigations, and even generate it from arbitrary file-path arrays for remote or dynamically-sourced content.

​
getPageMap()

Retrieves the compiled page-map tree for a given route. Under the hood, Nextra generates the tree during the webpack/Turbopack build and embeds it as a module; getPageMap() imports that module and navigates to the requested route segment. 
async function getPageMap(route?: string): Promise<PageMapItem[]>
​
route
string
default:"'/'"
The route path to retrieve the page map for. Use / to get the full root tree, a segment like /blog to get just the children under that path, or a locale-prefixed path like /en when i18n is configured.
Returns Promise<PageMapItem[]> — an array of Folder, MdxFile, and MetaJsonFile items representing the content at the requested route.
getPageMap() throws an Error when the specified route segment does not exist in the compiled map. Make sure the route matches an actual folder in your content directory.

​
Usage in a root layout

The most common usage is passing the full page map to your theme’s layout component so it can render the sidebar and breadcrumbs:
app/layout.tsx
import { getPageMap } from 'nextra/page-map'

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const pageMap = await getPageMap()
  return (
    <html>
      <body>
        <DocsLayout pageMap={pageMap}>{children}</DocsLayout>
      </body>
    </html>
  )
}

​
Scoping by route

You can pass a specific route to retrieve only the children of that section, useful for section-level layouts:
app/blog/layout.tsx
import { getPageMap } from 'nextra/page-map'

export default async function BlogLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const blogPageMap = await getPageMap('/blog')
  return <BlogSidebar pageMap={blogPageMap}>{children}</BlogSidebar>
}

​
normalizePageMap()

Normalizes a raw page map, resolving page titles and order from _meta.js files and filling in default titles derived from filenames where no explicit title is set. 
function normalizePageMap(pageMap: PageMapItem[]): PageMapItem[]
​
pageMap
PageMapItem[]
required
A raw page-map array, typically as returned by getPageMap() or built via convertToPageMap().
Returns PageMapItem[] — a new array with titles resolved and items ordered according to their corresponding _meta configuration.

​
convertToPageMap()

Converts a flat array of file paths into a hierarchical PageMapItem tree. This is the primary entry point for working with remote or externally-sourced content where you can enumerate file paths but don’t have them on disk at build time. 
function convertToPageMap(options: {
  filePaths: string[]
  basePath?: string
  locale?: string
}): { pageMap: PageMapItem[]; mdxPages: Record<string, string> }
​
filePaths
string[]
required
An array of file paths relative to the project root. Paths may originate from content/, src/content/, or app/ directories. _meta files are automatically detected and separated from page files.
​
basePath
string
An optional path prefix to prepend to all resolved routes. Useful when the content is mounted at a sub-path (e.g. /docs).
​
locale
string
When i18n is enabled, pass the locale string so locale-prefixed path segments are stripped correctly from the generated routes.
Returns an object with:
​
pageMap
PageMapItem[]
The hierarchical page-map tree built from the provided file paths.
​
mdxPages
Record<string, string>
A flat map from each resolved route string to its original file path (relative to the content/ directory, with locale prefix stripped if provided). Useful for looking up source files when rendering dynamic segments.
import { convertToPageMap } from 'nextra/page-map'
import { fetchFilepathsFromGitHub } from 'nextra/fetch-filepaths-from-github'

const filePaths = await fetchFilepathsFromGitHub('myorg', 'myrepo', 'main')

const { pageMap, mdxPages } = convertToPageMap({
  filePaths,
  basePath: 'remote',
})

​
mergeMetaWithPageMap()

Merges an external meta configuration record into an existing page map. Use this when you fetch _meta data from a CMS or remote source and need to apply it to a page map that was built from file paths alone. 
function mergeMetaWithPageMap(
  pageMap: PageMapItem[],
  meta: DynamicMeta
): PageMapItem[]
​
pageMap
PageMapItem[]
required
The base page map to merge into.
​
meta
DynamicMeta
required
A Record<string, DynamicMetaItem> describing titles, ordering, separators, and other metadata — the same shape as a _meta.js export.
Returns PageMapItem[] — the merged page map with meta applied.

​
createIndexPage()

Generates compiled MDX source code for an auto-generated index page that lists all pages in the provided map as a card grid, grouping them under separator headings where present. 
async function createIndexPage(pageMap: PageMapItem[]): Promise<string>
​
pageMap
PageMapItem[]
required
The page-map slice to generate cards for. MetaJsonFile items are skipped; separator items become ## headings.
Returns Promise<string> — serialised JavaScript (the output of compileMdx) that can be passed directly to MDXRemote or written to a dynamic route.
app/docs/page.tsx
import { getPageMap, createIndexPage } from 'nextra/page-map'
import { MDXRemote } from 'nextra/mdx-remote'

export default async function DocsIndex() {
  const pageMap = await getPageMap('/docs')
  const compiledSource = await createIndexPage(pageMap)
  return <MDXRemote compiledSource={compiledSource} />
}

​
getIndexPageMap()

Returns a simplified representation of a page map suitable for rendering a custom index UI. The result is an array where each entry is either a separator item or a group of MdxFile items. 
function getIndexPageMap(
  pageMap: PageMapItem[]
): (SeparatorItem | MdxFile[])[]
​
pageMap
PageMapItem[]
required
The page-map slice to process.
Returns (SeparatorItem | MdxFile[])[] — an array that alternates between separator headings and arrays of page items, ready to be mapped over in a React component.

​
getMetadata()

A utility that resolves Next.js Metadata from a dynamically imported page module, handling both static metadata exports and async generateMetadata functions. 
function getMetadata(
  page:
    | { metadata: Metadata }
    | { generateMetadata?: (props: object) => Promise<Metadata> }
): Promise<Metadata> | Metadata

​
Types

​
PageMapItem

type PageMapItem = Folder | MdxFile | MetaJsonFile

​
Folder

​
name
string
The directory name as it appears on the filesystem.
​
route
string
The URL path segment for this folder, e.g. '/blog'.
​
children
PageMapItem[]
Nested page-map items contained within this folder.

​
MdxFile

​
name
string
The filename without extension, e.g. 'getting-started'.
​
route
string
The full URL route for this page, e.g. '/docs/getting-started'.
​
frontMatter
FrontMatter
Optional. The parsed YAML front matter from the MDX file, typed as Record<string, any>.

​
MetaJsonFile

​
data
Record<string, Meta>
The parsed contents of a _meta.js (or _meta.json) file, keyed by page name. Each value is either a plain string title or a metadata object.
To narrow a PageMapItem to a specific sub-type, check for the discriminating property: 'children' in item for Folder, 'route' in item for MdxFile, and 'data' in item for MetaJsonFile.

Build docs developers (and LLMs) love

Get started for freeTalk to us