# Nextra — Next.js-Based Documentation and Content Framework

> Nextra is a documentation framework built on Next.js that turns MDX files into a polished, searchable documentation site with minimal configuration.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Nextra — Next.js-Based Documentation and Content Framework

## Quick Use
```bash
npx create-next-app --example https://github.com/shuding/nextra-docs-template my-docs
cd my-docs
npm run dev
```

## Introduction
Documentation is often an afterthought because setting up a docs site requires choosing and configuring a static site generator, theme, search, and navigation. Nextra simplifies this by providing a complete documentation framework on top of Next.js, where you write MDX files and get a production-ready docs site with search, sidebar navigation, and dark mode out of the box.

## What Nextra Does
- Transforms MDX files in a pages directory into a fully navigable documentation website
- Provides built-in full-text search without requiring an external search service
- Auto-generates sidebar navigation from the file system structure
- Supports MDX components so you can embed interactive React elements in documentation
- Includes blog and docs themes with dark mode, i18n, and SEO metadata

## Architecture Overview
Nextra is a Next.js plugin that adds an MDX loader and a set of layout components. During build, it scans the pages directory for .md and .mdx files, processes frontmatter for metadata, and generates a page map that drives sidebar navigation and breadcrumbs. The docs theme wraps each page in a layout with a collapsible sidebar, table of contents, and edit-on-GitHub links. Search is powered by FlexSearch, which indexes page content at build time and runs entirely client-side. Because Nextra is built on Next.js, you can add dynamic pages, API routes, or any React component alongside your documentation.

## Self-Hosting & Configuration
- Install nextra and a theme package: npm install nextra nextra-theme-docs
- Configure next.config.js with the Nextra plugin and specify the theme
- Organize docs as MDX files under the pages directory with _meta.json for ordering
- Customize the theme via theme.config.tsx with logo, footer, navigation links, and colors
- Deploy to Vercel, Netlify, or any Node.js host with next build && next export for static output

## Key Features
- File-system routing means adding a page is as simple as creating a new MDX file
- Client-side full-text search works offline and requires no external service or API key
- MDX support lets you embed live React components, code playgrounds, and interactive demos
- Internationalization support with per-locale page directories and language switching
- Built-in syntax highlighting with configurable themes and line number display

## Comparison with Similar Tools
- **Docusaurus** — React-based docs framework by Meta; Nextra leverages Next.js for SSR and hybrid rendering
- **VitePress** — Vue-based and fast; Nextra is the natural choice for teams already using React and Next.js
- **Starlight** — Astro-based docs framework; Nextra offers tighter integration with the Next.js ecosystem
- **GitBook** — Hosted docs platform; Nextra is self-hosted and fully customizable
- **MkDocs** — Python-based with Markdown; Nextra supports MDX with embedded React components

## FAQ
**Q: Can I use Nextra for a blog instead of documentation?**
A: Yes. Nextra includes a blog theme with RSS feed, tags, and author pages alongside the docs theme.

**Q: Does Nextra support static export?**
A: Yes. You can use Next.js static export to generate a fully static site deployable to any CDN.

**Q: How do I customize the sidebar order?**
A: Create a _meta.json file in each directory to define page order, titles, and whether items are hidden or external links.

**Q: Can I add custom React components to my docs pages?**
A: Yes. MDX lets you import and use any React component directly in your documentation files.

## Sources
- https://github.com/shuding/nextra
- https://nextra.site/

---
Source: https://tokrepo.com/en/workflows/nextra-next-js-based-documentation-content-framework-475900bb
Author: AI Open Source