Add an MDX Page to an Existing Nextra Documentation Starter

To add a page to an existing Nextra documentation starter, make two changes: create the .mdx file under pages/, then add its filename key to the starter’s _meta.json using the format already in that file. Check both results locally. A page that opens by URL may still be hard for readers to find if its navigation entry is missing.

Check the starter before editing

This walkthrough is for a starter that already uses a pages/ directory for its documentation. Nextra describes its documentation pages as using Next.js file-system routing and MDX. The file’s location is therefore part of the URL decision; navigation metadata is a separate part of the authoring work. This is not a recipe for installing Nextra into a blank Next.js app or for adding a page under app/.

Start with the checkout’s README. Then open package.json to see which development script it defines and which Next.js and Nextra dependencies the project declares. Identify the package manager from the lockfile rather than guessing from another starter’s instructions. These checks give you the commands and conventions for the project in front of you, without assuming that every Nextra documentation starter is arranged alike.

Before creating a file, browse pages/ and open the _meta.json your starter uses for its existing pages. Notice how its keys correspond to MDX filenames, how it writes labels, and how the current entries appear in the rendered navigation. Keep that file open: it is easier to make a small edit that matches nearby entries than to replace working metadata with an example from a different checkout.

Create the MDX page

For a straightforward page, create pages/troubleshooting.mdx. Its intended route is /troubleshooting: the name under pages/ supplies the route segment. Keeping this first addition at the top level also makes it easy to compare with other files and metadata entries already present there.

Add a short page with content you can recognize when you open the route:

# Troubleshooting

Use these checks when a documentation example produces an unexpected result.

## Inspect the value

Log the value before comparing it with the example:

```js
const section = 'guides'
console.log(section)
```

If the value differs, check where your example assigns it.

The heading, prose, and code fence give you three visible things to verify. Nextra’s MDX support also allows components inside Markdown, but this page does not need one merely to display a small code example. Save the file at the path you intend to visit; a good navigation label cannot fix a page saved at the wrong route.

Add the filename key to navigation

A Nextra documentation walkthrough advises adding the name of a new .mdx file as a key in _meta.json. For troubleshooting.mdx, find the existing metadata file and add the corresponding filename key in the same format as its neighboring entries. Give it the label you want readers to see, using the label format that checkout already uses. Preserve its other entries.

Do not treat the metadata edit as a substitute for checking the interface. The file path answers where the page opens; the rendered navigation answers whether readers can find it and where they will look for it. If placement matters, compare the new entry with adjacent entries in the existing metadata, then inspect the navigation in the browser rather than assuming the edit produced the intended order.

Check the page and its navigation entry

Run the development script documented by the starter, using the package manager indicated by its lockfile. Open the local site at the address printed by that command, then visit /troubleshooting. Confirm that the Troubleshooting heading, explanatory text, and JavaScript example render. Next, find the page in the site’s navigation and follow that entry back to the same route. Check both its label and its position among the other pages.

If the URL fails, first recheck that the file is actually pages/troubleshooting.mdx and inspect its MDX content for an editing mistake. If the URL works but the page is absent from navigation or appears in the wrong place, return to the starter’s _meta.json: compare the new filename key, label, and position with the entries already used there. Those are different failures, so checking the route before the navigation keeps the diagnosis focused.