_meta.js File

Organizing Files

Nextra allows you to organize files in the following ways:

• In Next.js’ app directory: Nextra gathers all page files, including page.md and page.mdx files as well as _meta files.

• In Nextra’s content directory: Nextra collects all .md and .mdx files, along with _meta files.

Afterward, Nextra generates a pageMap array containing information about your entire site’s routes and directories structure. Features such as the navigation bar and sidebar can be generated based on the pageMap information.

Below the same file-based routing structure is represented for content and app-only directories:

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • about
    • _meta.js
    • index.mdx
    • legal.md
  • _meta.js
  • contact.md
  • index.mdx

Using page.mdx files
• app
  • about
    • legal
    • _meta.js
    • page.mdx
  • contact
  • _meta.js
  • layout.jsx
  • page.mdx

The generated pageMap will be:

[
  // 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"
  }
]

And the global pageMap will be imported to each page by Nextra. Then, configured theme will render the actual UI with that pageMap.

In Nextra, the site and page structure can be configured via the co-located _meta files. Those configurations affect the overall layout of the theme, especially the navigation bar and the sidebar.

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • _meta.js
  • contact.md
  • index.mdx
  • about
    • _meta.js
    • legal.md
    • index.mdx

Using page.mdx files
• app
  • about
    • legal
    • _meta.js
    • page.mdx
  • contact
  • _meta.js
  • layout.jsx
  • page.mdx

It’s very common to customize each page’s title, rather than just relying on filenames. Having a page titled “Index” lacks clarity. It is preferable to assign a meaningful title that accurately represents the content, such as “Home”.

That’s where _meta files comes in. You can have an _meta file in each directory, and it will be used to override the default configuration of each page.

Example

Put this in your content/_meta.js file:

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

It tells Nextra the order of each page, and the correct title.

Alternatively, you can do it with title property and have other configurations in there as well:

export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  about: {
    title: 'About Us'
    // ... extra configurations
  }
}

The extra configurations are passed to the theme as additional information.

Pages

The title and order of a page shown in the sidebar should be configured in the _meta file as key-value pairs. For example, if you have the following file structure:

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • _meta.js
  • about.mdx
  • contact.mdx
  • index.mdx

Using page.mdx files
• app
  • about
  • contact
  • _meta.js
  • layout.jsx
  • page.mdx

You can define how the pages are shown in the sidebar via the _meta file:

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

Folders

Folders can be configured in the same way as pages. For example:

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • fruits
    • _meta.js
    • apple.mdx
    • banana.mdx
  • _meta.js
  • about.mdx
  • contact.mdx
  • index.mdx

Using page.mdx files
• app
  • about
  • contact
  • fruits
    • apple
    • banana
    • _meta.js
  • _meta.js
  • layout.jsx
  • page.mdx

The top-level _meta file contains the meta information for the top-level pages and folders:

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

And the nested _meta file contains the meta information for pages in the same folder:

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

This way, information for pages are grouped together in directories. You can move directories around without having to change the _meta file.

Folders with Index Page

To create a folder with an index page, add asIndexPage: true to its front matter.

For example, to create a /fruits route, setting asIndexPage: true tells Nextra that /fruits is a folder with an index page. Clicking the folder in the sidebar will expand it and display the MDX page.

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • fruits
    • _meta.js
    • apple.mdx
    • banana.mdx
    • index.mdx
  • _meta.js
  • about.mdx
  • contact.mdx
  • index.mdx

Using page.mdx files
• app
  • about
  • contact
  • fruits
    • apple
    • banana
    • _meta.js
    • page.mdx
  • _meta.js
  • layout.jsx
  • page.mdx

---
asIndexPage: true
---

External Links

You can add external links to the sidebar by adding an item with href in _meta file:

export default {
  index: 'My Homepage',
  contact: 'Contact Us',
  fruits: 'Delicious Fruits',
  about: 'About Us',
  github_link: {
    title: 'Nextra',
    href: 'https://github.com/shuding/nextra'
  }
}

Hidden Routes

By default, all MDX routes in the filesystem will be shown on the sidebar. But you can hide a specific pages or folders by using the display: 'hidden' configuration:

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

The page will still be accessible via the /contact URL, but it will not be shown in the sidebar.

Navbar Items

Sub Docs

By defining a top-level page or folder as type: 'page', it will be shown as a special page on the navigation bar, instead of the sidebar. With this feature, you can have multiple “sub docs”, and special pages or links such as “Contact Us” that are always visible.

For example, you can have 2 docs folders frameworks and fruits in your project:

Using content directory
• app
  • [[...mdxPath]]
    • page.jsx
  • layout.jsx
• content
  • frameworks
    • react.mdx
    • svelte.mdx
    • vue.mdx
  • fruits
    • apple.mdx
    • banana.mdx
  • _meta.js
  • about.mdx
  • index.mdx

Using page.mdx files
• app
  • about
  • frameworks
    • react
    • svelte
    • vue
  • fruits
    • apple
    • banana
  • _meta.js
  • layout.jsx
  • page.mdx

In your top-level _meta file, you can set everything as a page, instead of a normal sidebar item:

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

And it will look like this:

You can also hide links like Home from the navbar with the display: 'hidden' option.

Menus

You can also add menus to the navbar using type: 'menu' and the 'items' option:

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

Links

Same as the External Links option, you can have external links in the navbar too:

export default {
  index: {
    title: 'Home',
    type: 'page'
  },
  about: {
    title: 'About',
    type: 'page'
  },
  contact: {
    title: 'Contact Us',
    type: 'page',
    href: 'https://example.com/contact'
  }
}

Fallbacks

In the Sub Docs example above, we have to define the type: 'page' option for every page. To make it easier, you can use the '*' key to define the fallback configuration for all items in this folder:

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

They are equivalent where all items have type: 'page' set.

Separators

You can use a “placeholder” item with type: 'separator' to create a separator line between items in the sidebar:

export default {
  index: 'My Homepage',
  '---': {
    type: 'separator'
  },
  contact: 'Contact Us'
}

Theme Configuration

You can configure the theme for each page using the 'theme' option. For example, you can disable or enable specific components for specific pages:

export default {
  about: {
    theme: {
      sidebar: false
    }
  }
}

Layouts

By default, each page has layout: 'default' in their theme config, which is the default behavior. You might want to render some page with the full container width and height, but keep all the other styles. You can use the 'full' layout to do that:

export default {
  about: {
    theme: {
      layout: 'full'
    }
  }
}

Typesetting

The 'typesetting' option controls typesetting details like font features, heading styles and components like <li> and <code>. There are 'default' and 'article' typesettings available in the docs theme.

The default one is suitable for most cases like documentation, but you can use the 'article' typesetting to make it look like an elegant article page:

export default {
  about: {
    theme: {
      typesetting: 'article'
    }
  }
}

Sorting Pages Alphabetically

You can use ESLint’s built-in sort-keys rule, append /* eslint sort-keys: error */ comment at the top of your _meta file, and you will receive ESLint’s errors about incorrect order.

Allowed Keys Values

The type of your _meta keys should be always string and not number since numbers are always ordered first  for JavaScript objects.

Following:

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

Will be converted to:

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