Nextra Architecture Expert

Next.js-Based Documentation Framework

Focus: MDX Authoring, File-Based Routing, Theme Configuration
Stack: Next.js 14, Nextra 3, MDX 3, Storybook (optional)

Overview

Nextra is a static site generator built on Next.js, optimized for documentation with zero-config MDX and automatic routing.

Core Features

• File-System Routing: Automatic route generation from folder structure.
• MDX Support: Markdown + React components (.mdx files).
• Theme System: Pre-built themes (docs, blog) or custom.
• i18n: Built-in internationalization support.
• Search: Built-in Algolia/Flexsearch integration.

Implementation Patterns

1. Installation & Setup

npm install next nextra nextra-theme-docs react react-dom

next.config.js:

const withNextra = require("nextra")({
  theme: "nextra-theme-docs",
  themeConfig: "./theme.config.tsx",
});

module.exports = withNextra();

theme.config.tsx (Core Configuration):

import { DocsThemeConfig } from "nextra-theme-docs";

const config: DocsThemeConfig = {
  logo: <span>My Docs</span>,
  project: {
    link: "https://github.com/user/project",
  },
  docsRepositoryBase: "https://github.com/user/project/tree/main/docs",
  footer: {
    text: "© 2025 My Company",
  },
  sidebar: {
    defaultMenuCollapseLevel: 1,
  },
  darkMode: true,
};

export default config;

2. Content Structure

pages/
├── index.mdx          # Homepage
├── _meta.json         # Navigation metadata
├── getting-started/
│   ├── installation.mdx
│   └── quickstart.mdx
└── api-reference/
    ├── functions.mdx
    └── classes.mdx

_meta.json (Navigation Config):

{
  "index": "Introduction",
  "getting-started": "Getting Started",
  "api-reference": "API Reference"
}

3. MDX Components & Syntax

Tabs, Callouts, Code Blocks:

---
title: Quick Start Guide
---

import { Tabs, Callout } from "nextra/components";

# Quick Start

<Callout type="info">This guide assumes Node.js 18+ is installed.</Callout>

<Tabs items={["npm", "yarn", "pnpm"]}>
  <Tabs.Tab>```bash npm install my-package ```</Tabs.Tab>
  <Tabs.Tab>```bash yarn add my-package ```</Tabs.Tab>
  <Tabs.Tab>```bash pnpm add my-package ```</Tabs.Tab>
</Tabs>

## Features

```typescript showLineNumbers {3-5}
function hello(name: string) {
  // Highlighted lines
  console.log(`Hello, ${name}!`);
  return true;
}
```

### 4. Custom Components

Embed React components in MDX:

```tsx
// components/DemoButton.tsx
export function DemoButton({ text }: { text: string }) {
  return <button className="btn-primary">{text}</button>;
}

import { DemoButton } from "../components/DemoButton";

# My Page

Click the button below:

<DemoButton text="Try it now!" />

5. Localization (i18n)

Create separate folders per locale:

pages/
├── en/
│   └── docs.mdx
├── ko/
│   └── docs.mdx
└── _meta.json  # Define i18n settings

next.config.js (i18n):

const withNextra = require("nextra")({
  theme: "nextra-theme-docs",
  themeConfig: "./theme.config.tsx",
  i18n: {
    locales: ["en", "ko", "ja"],
    defaultLocale: "en",
  },
});

module.exports = withNextra();

Best Practices

1. Consistent Frontmatter: Always define title and optional description in MDX.
2. _meta.json for Structure: Don't rely on alphabetical ordering; use _meta.json.
3. Component Imports: Keep custom components in /components for clarity.
4. Static Export: For GitHub Pages, set output: 'export' in next.config.js.

Validation Checklist

• Routing: Does folder structure match navigation?
• _meta.json: Are all pages listed?
• Frontmatter: Every MDX has title?
• Code Blocks: Language hints added (```typescript)?
• Dark Mode: Theme toggle configured?

Related Skills

• moai-lib-shadcn-ui: Component library for MDX
• moai-domain-frontend: Next.js patterns
• moai-project-documentation: Documentation standards

Last Updated: 2025-11-20