moai-library-nextra

Original source / Raw SKILL.md

---
name: moai-library-nextra
description: Enterprise Nextra documentation framework with Next.js. Use when building documentation sites, knowledge bases, or API reference documentation.
version: 2.1.0
modularized: true
user-invocable: false
updated: 2026-01-08
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - mcp__context7__resolve-library-id
  - mcp__context7__get-library-docs
aliases:
 - moai-library-nextra
category: library
---

## Quick Reference (30 seconds)

Purpose: Build professional documentation sites with Nextra + Next.js.

Nextra Advantages:

- Zero config MDX (Markdown + JSX seamlessly)
- File-system routing (automatic routes)
- Performance optimized (code splitting, prefetching)
- Theme system (pluggable, customizable)
- i18n built-in (internationalization)

Core Files:

- `pages/` - Documentation pages (MDX)
- `theme.config.tsx` - Site configuration
- `_meta.js` - Navigation structure

## Implementation Guide (5 minutes)

### Features

- Nextra 3.x/4.x documentation framework architecture patterns
- Next.js 14/15 integration with optimal configuration
- Theme customization via theme.config.tsx or Layout props
- Advanced search with FlexSearch integration
- Internationalization (i18n) support
- MDX-powered content with React components
- App Router support (Nextra 4.x) with Turbopack compatibility

### When to Use

- Building documentation sites with modern React features
- Creating knowledge bases with advanced search capabilities
- Developing multi-language documentation portals
- Implementing custom documentation themes
- Integrating interactive examples in technical docs

### Core Patterns

Pattern 1: Nextra Project Setup

```bash
# Initialize Nextra docs site
npx create-nextra-app@latest my-docs --template docs

# Project structure
pages/
 _app.tsx (custom App component)
 index.mdx (home page)
 docs/
 guide.mdx
 api.mdx
 _meta.json (navigation config)
```

Pattern 2: Custom Theme Configuration

```typescript
// theme.config.tsx
export default {
 logo: <span>My Documentation</span>,
 project: { link: "https://github.com/user/repo" },
 docsRepositoryBase: "https://github.com/user/repo/tree/main",
 useNextSeoProps: () => ({
 titleTemplate: "%s – My Docs",
 }),
};
```

Pattern 3: MDX with React Components

```mdx
import { Callout } from "nextra/components";

# API Reference

<Callout type="info">This API requires authentication.</Callout>

<CustomCodeBlock language="typescript">// Your code here</CustomCodeBlock>
```

## Core Patterns (5-10 minutes)

### Pattern 1: Project Structure

Key Concept: Organize documentation files logically

Recommended Structure:

```
docs/
 pages/
 index.mdx # Homepage
 getting-started/
 _meta.js # Section config
 index.mdx
 installation.mdx
 guides/
 _meta.js
 basics.mdx
 advanced.mdx
 api/
 _meta.js
 reference.mdx
 public/ # Static assets
 theme.config.tsx # Main config
 next.config.js # Next.js config
 package.json
```

### Pattern 2: Theme Configuration

Key Concept: Customize site appearance and behavior

Essential Config:

```typescript
const config: DocsThemeConfig = {
 // Branding
 logo: <span>My Docs</span>,
 logoLink: "/",

 // Navigation
 project: { link: "https://github.com/..." },
 docsRepositoryBase: "https://github.com/.../tree/main",

 // Sidebar
 sidebar: {
 defaultMenuCollapseLevel: 1,
 toggleButton: true,
 },

 // Table of contents
 toc: { backToTop: true },

 // Footer
 footer: { text: "Built with Nextra" },
};
```

### Pattern 3: Navigation Structure (\_meta.js)

Key Concept: Control sidebar menu and page ordering

Example:

```javascript
// pages/guides/_meta.js
export default {
 index: "Overview",
 "getting-started": "Getting Started",
 basics: "Basic Concepts",
 advanced: "Advanced Topics",
 "---": "", // Separator
 faq: "FAQ",
};
```

### Pattern 4: MDX Content & JSX Integration

Key Concept: Mix Markdown with React components

Example:

```mdx
# My Documentation

<div className="bg-blue-100 p-4">
 <h3>Important Note</h3>
 <p>You can embed React components directly!</p>
</div>

## Code Examples

export const MyComponent = () => (
 <button onClick={() => alert("Clicked!")}>Click me</button>
);

<MyComponent />
```

### Pattern 5: Search & SEO Optimization

Key Concept: Make documentation discoverable

Config:

```typescript
// theme.config.tsx
const config: DocsThemeConfig = {
 // Enable search
 search: {
 placeholder: "Search docs...",
 },

 // SEO metadata
 head: (
 <>
 <meta name="og:title" content="My Documentation" />
 <meta name="og:description" content="Complete guide" />
 <meta name="og:image" content="/og-image.png" />
 </>
 ),

 // Analytics
 useNextSeoProps() {
 return {
 titleTemplate: "%s - My Docs",
 };
 },
};
```

---

## Advanced Documentation

This Skill uses Progressive Disclosure. For detailed patterns:

- [modules/configuration.md](modules/configuration.md) - Complete theme.config reference
- [modules/mdx-components.md](modules/mdx-components.md) - MDX component library
- [modules/i18n-setup.md](modules/i18n-setup.md) - Internationalization guide
- [modules/deployment.md](modules/deployment.md) - Hosting & deployment

---

## Theme Options

Built-in Themes:

- nextra-theme-docs (recommended for documentation)
- nextra-theme-blog (for blogs)

Customization:

- CSS variables for colors
- Custom sidebar components
- Footer customization
- Navigation layout

---

## Deployment

Popular Platforms:

- Vercel (zero-config, recommended)
- GitHub Pages (free, self-hosted)
- Netlify (flexible, CI/CD)
- Custom servers (full control)

Vercel Deployment:

```bash
npm install -g vercel
vercel
# Select project and deploy
```

---

## Integration with Other Skills

Complementary Skills:

- Skill("moai-docs-generation") - Auto-generate docs from code
- Skill("moai-workflow-docs") - Validate documentation quality
- Skill("moai-cc-claude-md") - Markdown formatting

---

## Version History

2.1.0 (2025-12-30)

- Updated configuration.md with complete Nextra-specific theme.config.tsx patterns
- Added Nextra 4.x App Router configuration patterns
- Updated version compatibility for Next.js 14/15
- Added Turbopack support documentation

2.0.0 (2025-11-23)

- Refactored with Progressive Disclosure
- Configuration patterns highlighted
- MDX integration guide

1.0.0 (2025-11-12)

- Nextra architecture guide
- Theme configuration
- i18n support

---

Maintained by: alfred
Domain: Documentation Architecture
Generated with: MoAI-ADK Skill Factory

---

## Works Well With

Agents:
- workflow-docs - Documentation generation
- code-frontend - Nextra implementation
- workflow-spec - Architecture documentation

Skills:
- moai-docs-generation - Content generation
- moai-workflow-docs - Documentation validation
- moai-library-mermaid - Diagram integration

Commands:
- `/moai:3-sync` - Documentation deployment
- `/moai:0-project` - Nextra project initialization


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### modules/configuration.md

```markdown
---
name: configuration
parent: moai-library-nextra
description: Complete Nextra theme.config.tsx reference and configuration patterns
---

# Nextra Theme Configuration Guide

## Overview

Complete reference for configuring Nextra documentation sites using theme.config.tsx (Nextra 3.x) or Layout props (Nextra 4.x with App Router).

## Nextra 3.x Theme Configuration (Pages Router)

### Complete theme.config.tsx Reference

```typescript
// theme.config.tsx
import { DocsThemeConfig } from 'nextra-theme-docs'

const config: DocsThemeConfig = {
  // Branding
  logo: <span className="font-bold">My Documentation</span>,
  logoLink: '/',

  // Project Links
  project: {
    link: 'https://github.com/username/project',
    icon: <GitHubIcon />,  // Optional custom icon
  },

  // Chat/Discord Link
  chat: {
    link: 'https://discord.gg/your-server',
    icon: <DiscordIcon />,
  },

  // Repository Base for Edit Links
  docsRepositoryBase: 'https://github.com/username/project/tree/main/docs',

  // SEO Configuration
  useNextSeoProps() {
    return {
      titleTemplate: '%s - My Documentation',
    }
  },

  // Head Elements
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="My Documentation" />
      <meta property="og:description" content="Comprehensive project documentation" />
      <link rel="icon" href="/favicon.ico" />
    </>
  ),

  // Primary Color Hue
  primaryHue: {
    dark: 210,
    light: 220,
  },

  // Sidebar Configuration
  sidebar: {
    defaultMenuCollapseLevel: 1,
    toggleButton: true,
    autoCollapse: false,
  },

  // Table of Contents
  toc: {
    title: 'On This Page',
    float: true,
    backToTop: true,
    extraContent: null,
  },

  // Navigation
  navigation: {
    prev: true,
    next: true,
  },

  // Edit Link
  editLink: {
    text: 'Edit this page on GitHub',
  },

  // Feedback
  feedback: {
    content: 'Question? Give us feedback',
    labels: 'feedback',
    useLink: () => 'https://github.com/username/project/issues/new',
  },

  // Footer
  footer: {
    text: (
      <span>
        MIT {new Date().getFullYear()} - My Project
      </span>
    ),
  },

  // Dark Mode
  darkMode: true,

  // Theme Switch Labels
  themeSwitch: {
    useOptions() {
      return {
        light: 'Light',
        dark: 'Dark',
        system: 'System',
      }
    },
  },

  // Git Timestamp
  gitTimestamp: function GitTimestamp({ timestamp }) {
    return (
      <span>
        Last updated: {timestamp.toLocaleDateString()}
      </span>
    )
  },

  // Search Configuration
  search: {
    placeholder: 'Search documentation...',
    loading: 'Loading...',
    emptyResult: 'No results found',
    error: 'Search failed',
  },

  // Navbar Extra Content
  navbar: {
    extraContent: null,
  },

  // Banner
  banner: {
    key: 'release-banner',
    text: 'Version 2.0 is now available!',
    dismissible: true,
  },

  // Internationalization
  i18n: [
    { locale: 'en', text: 'English' },
    { locale: 'ko', text: 'Korean' },
    { locale: 'ja', text: 'Japanese' },
  ],
}

export default config
```

## Nextra 4.x Configuration (App Router)

### Layout Component Props

```typescript
// app/layout.tsx
import { Layout } from 'nextra-theme-docs'
import { getPageMap } from 'nextra/page-map'
import { Banner, Navbar, Footer, Search } from '@/components'

export default async function RootLayout({ children }) {
  const pageMap = await getPageMap()

  return (
    <html lang="en">
      <body>
        <Layout
          pageMap={pageMap}
          banner={<Banner />}
          navbar={<Navbar />}
          footer={<Footer />}
          search={<Search />}
          docsRepositoryBase="https://github.com/username/project/tree/main"
          darkMode={true}
          editLink="Edit this page on GitHub"
          feedback={{
            content: 'Question? Give us feedback',
            labels: 'feedback',
          }}
          i18n={[
            { locale: 'en', name: 'English' },
            { locale: 'ko', name: 'Korean' },
          ]}
          lastUpdated={<LastUpdated />}
          navigation={{ prev: true, next: true }}
          sidebar={{
            autoCollapse: false,
            defaultMenuCollapseLevel: 2,
            defaultOpen: true,
            toggleButton: true,
          }}
          toc={{
            title: 'On This Page',
            float: true,
            backToTop: 'Back to top',
            extraContent: null,
          }}
          themeSwitch={{
            dark: 'Dark',
            light: 'Light',
            system: 'System',
          }}
          nextThemes={{
            attribute: 'class',
            defaultTheme: 'system',
            disableTransitionOnChange: false,
          }}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}
```

## Configuration Patterns by Use Case

### Minimal Documentation Site

```typescript
const config: DocsThemeConfig = {
  logo: <span>Docs</span>,
  project: { link: 'https://github.com/user/repo' },
  docsRepositoryBase: 'https://github.com/user/repo/tree/main',
}
```

### Enterprise Documentation

```typescript
const config: DocsThemeConfig = {
  logo: <CompanyLogo />,
  logoLink: '/',
  project: { link: 'https://github.com/company/product' },
  docsRepositoryBase: 'https://github.com/company/product/tree/main/docs',

  sidebar: {
    defaultMenuCollapseLevel: 2,
    toggleButton: true,
    autoCollapse: true,
  },

  toc: {
    float: true,
    backToTop: true,
  },

  search: {
    placeholder: 'Search...',
  },

  footer: {
    text: <CompanyFooter />,
  },

  i18n: [
    { locale: 'en', text: 'English' },
    { locale: 'de', text: 'Deutsch' },
    { locale: 'fr', text: 'Francais' },
    { locale: 'ja', text: 'Japanese' },
  ],

  primaryHue: { dark: 200, light: 210 },
  darkMode: true,
}
```

### API Documentation

```typescript
const config: DocsThemeConfig = {
  logo: <span>API Reference</span>,

  // Wider content area for code examples
  toc: {
    float: false,
  },

  // Custom code block styling
  components: {
    pre: CustomCodeBlock,
  },

  // Version selector in navbar
  navbar: {
    extraContent: <VersionSelector />,
  },
}
```

## next.config.js Setup

### Nextra 3.x Configuration

```javascript
// next.config.js
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
  staticImage: true,
  flexSearch: true,
  defaultShowCopyCode: true,
})

module.exports = withNextra({
  reactStrictMode: true,
})
```

### Nextra 4.x with Next.js 15

```javascript
// next.config.mjs
import nextra from 'nextra'

const withNextra = nextra({
  // Nextra options
})

export default withNextra({
  // Next.js 15 options
  experimental: {
    turbopack: true,
  },
})
```

## Version Compatibility

Current stable versions as of 2025:
- Nextra 3.x: Compatible with Next.js 13.x and 14.x (Pages Router)
- Nextra 4.x: Compatible with Next.js 14.x and 15.x (App Router, Turbopack support)

Migration from Nextra 3 to 4 requires converting from theme.config.tsx to Layout component props.

---

Last Updated: 2025-12-30
Status: Production Ready
Reference: https://nextra.site/docs/docs-theme/theme-configuration

```

### modules/mdx-components.md

```markdown
# MDX Components

## Overview

Reusable MDX components for enhanced documentation.

## Core Components

### Callout Component

```mdx
<Callout type="info">
 Important information here
</Callout>

<Callout type="warning">
 Warning message
</Callout>
```

### Code Block Component

```mdx
<CodeBlock language="python" highlight="2,4-6">
{`
def example():
 # Highlighted line
 result = process()
 # More highlighted lines
 return result
`}
</CodeBlock>
```

## Custom Components

### Tabs Component

```mdx
<Tabs>
 <Tab label="Python">
 Python code example
 </Tab>
 <Tab label="JavaScript">
 JavaScript code example
 </Tab>
</Tabs>
```

---
Last Updated: 2025-11-23
Status: Production Ready

```

### modules/i18n-setup.md

```markdown
# Internationalization Setup

## Overview

Multi-language documentation setup and management.

## Configuration

### I18n Config

```javascript
// next.config.js
module.exports = {
 i18n: {
 locales: ['en', 'ko', 'ja', 'zh'],
 defaultLocale: 'en'
 }
}
```

### Directory Structure

```
docs/
 en/
 index.md
 guide.md
 ko/
 index.md
 guide.md
 ja/
 index.md
 guide.md
```

## Translation Workflow

### Translation Files

```json
{
 "en": {
 "welcome": "Welcome",
 "guide": "Guide"
 },
 "ko": {
 "welcome": "",
 "guide": ""
 }
}
```

---
Last Updated: 2025-11-23
Status: Production Ready

```

### modules/deployment.md

```markdown
# Deployment Guide

## Overview

Production deployment strategies and best practices.

## Deployment Platforms

### Vercel Deployment

```bash
# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod
```

### Netlify Deployment

```bash
# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod
```

## CI/CD Deployment

### GitHub Actions

```yaml
name: Deploy
on:
 push:
 branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: actions/setup-node@v3
 - run: npm ci
 - run: npm run build
 - run: vercel --prod --token ${{ secrets.VERCEL_TOKEN }}
```

---
Last Updated: 2025-11-23
Status: Production Ready

```