Nextra is a great tool for building websites with Next.js and MDX. However, when I was starting out I felt their like blog theme had too much magic going on. To figure out what the heck is going I decided to create a custom Theme. I've used Nextra for documentation on another project, and the knowledge gained from writing a custom theme made move so much quicker.

In the tutorial we are going to walk through creating a personal blog with Nextra. We will go over both _meta.json, frontmatter, and auto generating links from the pageOpts prop.

Intuitively, most of the heavy lifting for a custom Nextra theme happens in theme.tsx.

Create a custom Nextra app

When promopted name your project. This command also defaults your next app to pnpm and typescript.

npx create-next-app@latest --eslint --src-dir --import-alias --use-pnpm --typescript --tailwind

When promopted about app directory, responsed no.

You cannot use Nextra with the experimental app directory.

Would you like to use experimental `app/` directory with this project? (No/Yes) No

Change directory into your project. If you named your project something other than my-next-app change the directory name to match.

cd my-next-app
pnpm i nextra

I think a key to success could be a mix of frontMatter for the post, and _meta.json for the parent level navigation.

frontMatter

Frontmatter is a way to identify metadata in Markdown files. Metadata can literally be anything you want it to be, but often it's used for data elements your page needs and you don't want to show directly. https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/

We are going to use frontMatter in our individual post

_meta.json

In nextra, another way to define routes and metadata is to use a _meta.json file. This file is used to define the routes and metadata for the parent level of the directory. This is great for defining the navigation of your site.

Routing

When working with a nextra theme, the ability to create a post and it automatically appear in the navigation bar can feel like magic. When a post doesn't appear and you have zero reason why, nextra starts to feel more like a dark art.

The nextra docs are in progress, and specifcally when working with a theme, I have found them difficult to draw direct answers from. Writing documentation is extremely hard, and this seems to be the love child of the wonderful Shu Ding, so I felt lucky to have the few resources I did. Hopefully I can turn some of this article into a PR helping explaining routing.