home / skills / shipshitdev / library / nextra-writer

nextra-writer skill

safe

This skill provides clear Nextra documentation guidance for Next.js projects, enabling MDX-based pages, navigation, and API docs with best practices.

npx playbooks add skill shipshitdev/library --skill nextra-writer

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.6 KB

---
name: nextra-writer
description: Expert in creating clear, comprehensive technical documentation with Nextra (Next.js-based docs framework), MDX, and modern documentation patterns. Use for documentation sites that need Next.js integration.
version: 1.0.0
tags:
  - documentation
  - nextra
  - nextjs
  - mdx
  - technical-writing
  - api-docs
  - react
  - typescript
auto_activate: true
---

# Nextra Technical Writer

Expert technical writer for creating documentation using Nextra, the Next.js-based documentation framework.

**Why Nextra:** Next.js integration, fast builds, automatic routing, full-text search, dark mode, and MDX support out of the box.

## When This Activates

- Creating or updating Nextra documentation (.md, .mdx)
- Configuring Nextra settings (next.config.mjs, theme.config.tsx)
- Writing API documentation
- Organizing documentation structure and navigation
- Setting up documentation search and navigation

## Tech Stack

| Technology | Version |
|------------|---------|
| Nextra | 3.x |
| Next.js | 14.x / 15.x |
| React | 18.x / 19.x |
| TypeScript | 5.x |
| MDX | 3.x |

## Quick Start

```bash
# Create new Nextra docs
bun create next-app docs --example nextra-docs-template

# Or add to existing Next.js project
bun add nextra nextra-theme-docs
```

## Project Structure

```
docs/
├── pages/
│   ├── _meta.json          # Navigation config
│   ├── index.mdx           # Home page
│   ├── getting-started.mdx
│   └── api/
│       ├── _meta.json
│       └── endpoints.mdx
├── theme.config.tsx        # Theme configuration
├── next.config.mjs         # Next.js + Nextra config
└── package.json
```

## Navigation

Configure via `_meta.json`:

```json
{
  "index": "Introduction",
  "getting-started": "Getting Started",
  "---": {
    "type": "separator"
  },
  "api": "API Reference"
}
```

## Key Features

| Feature | Pattern |
|---------|---------|
| Callouts | `<Callout type="info">` |
| Tabs | `<Tabs items={['npm', 'yarn']}>` |
| Cards | `<Cards>` component |
| Steps | `<Steps>` component |
| File Tree | `<FileTree>` component |

## Documentation Hierarchy

1. Quick Start (5-10 min)
2. Core Concepts
3. Feature Documentation
4. Guides & Tutorials
5. API Reference
6. Advanced Topics

## Integration

| Skill | When to Use |
|-------|-------------|
| `docs` | General technical writing |
| `api-design-expert` | API documentation structure |
| `frontend-design` | Custom documentation UI |

---

**For detailed configuration, MDX patterns, and component examples:** `references/full-guide.md`

Overview

This skill is an expert technical writer for building documentation sites with Nextra, the Next.js-based docs framework. I craft clear, consistent MDX pages, configure Nextra settings, and design navigation and search for modern docs. Use this skill to create maintainable, developer-friendly documentation tightly integrated with Next.js.

How this skill works

I inspect your docs folder, theme.config.tsx, next.config.mjs, and _meta.json navigation files to align structure and routing with Nextra conventions. I convert content into MDX, add components like Callout, Tabs, and Cards, and wire up full-text search and dark-mode-friendly styling. I produce structured page outlines, API reference templates, and actionable migration steps for existing Next.js projects.

When to use it

Creating a new Nextra documentation site or adding docs to an existing Next.js app
Converting Markdown into MDX with interactive components and consistent patterns
Designing documentation navigation, _meta.json, and hierarchical structure
Writing API reference pages and generating client-focused examples
Configuring Nextra-specific settings such as theme.config.tsx and next.config.mjs

Best practices

Start with a lightweight Quick Start page (5–10 minutes) and expand into core concepts
Keep navigation shallow: Quick Start, Concepts, Guides, API, Advanced Topics
Use MDX components (Callout, Tabs, Steps, Cards) for scannable, actionable docs
Store navigation in _meta.json and sync it with folder structure for automatic routing
Write API examples with request/response snippets and minimal, copy-pasteable code

Example use cases

Bootstrapping docs with Nextra and configuring theme.config.tsx for branded styling
Migrating existing Markdown docs to MDX and adding interactive code tabs
Creating a structured API reference folder with endpoint templates and examples
Implementing site search and dark mode with recommended Nextra options
Auditing docs structure and producing a prioritized content roadmap

FAQ

Which files should I edit to change navigation?

Edit the _meta.json files in your docs folders to adjust labels, order, and separators; the folder structure determines routing.

Can I use custom React components in MDX?

Yes—MDX supports React components like Callout, Tabs, and custom UI; register them in your MDX provider or theme setup.