majiayu000 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
# 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
// 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
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:
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:
// 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:
# 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 => alert("Clicked!")}>Click me</button>
);
<MyComponent />
Pattern 5: Search & SEO Optimization
Key Concept: Make documentation discoverable
Config:
// 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 - Complete theme.config reference
- modules/mdx-components.md - MDX component library
- modules/i18n-setup.md - Internationalization guide
- 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:
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