organize-files.mdx

Organize Files

Nextra first collects all your Markdown files and configurations from the pages directory, and then generates the “page map information” of your entire site, to render things such as the navigation bar and sidebar below:

 Example: [Nextra Docs Theme](/docs/docs-theme) has sidebar and navbar generated automatically from Markdown files.

Default Behavior

By default, the page map contains all .md and .mdx filenames and the directory structure, sorted alphabetically. Then, Nextra will use the title package to get formatted page names from filenames.

For example if you have the following structure:

pages/
  contact.md
  index.mdx
  about/
    legal.md
    index.mdx

The resolved page map will be (note that all names were sorted alphabetically):

[
  {
    name: 'About',
    children: [
      { name: 'Index' },
      { name: 'Legal' }
    ]
  },
  { name: 'Contact' },
  { name: 'Index' }
]

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

_meta.json

It’s very common to customize each page’s title, rather than just using the filename. For example it doesn’t make sense to have a page titled “Index”, but instead have a page titled “Home”.

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

pages/
  _meta.json
  contact.md
  index.mdx
  about/
    _meta.json
    legal.md
    index.mdx

And you can put this in your pages/_meta.json file:

{
  "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 and have other configurations in there as well:

{
  "index": "My Homepage",
  "contact": "Contact Us",
  "about": {
    "title": "About Us",
    "...extra configurations...": "..."
  }
}

The extra configurations are passed to the theme as additional information. Check the corresponding pages for more information:

import { Card, Cards } from '@components/card'

} title="Docs Theme →" href="/docs/docs-theme/page-configuration"/> } title="Blog Theme →" href="/docs/blog-theme/page-configuration"/>