Nextra Writer

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

Quick Start

# 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:

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

Key Features

Documentation Hierarchy

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

Integration

---

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

Nextra Technical Writer - Full Guide

Complete guide to creating documentation with Nextra, the Next.js-based documentation framework.

Project Setup

New Project

# Using template
bun create next-app docs --example nextra-docs-template

# Manual setup
bun add nextra nextra-theme-docs next react react-dom

Next.js Configuration

// next.config.mjs
import nextra from 'nextra';

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
  defaultShowCopyCode: true,
  staticImage: true,
});

export default withNextra({
  // Next.js config options
});

Theme Configuration

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

const config: DocsThemeConfig = {
  logo: <span>Project Name</span>,
  project: {
    link: 'https://github.com/org/project',
  },
  docsRepositoryBase: 'https://github.com/org/project/tree/main/docs',
  footer: {
    text: '© 2024 Project Name. All rights reserved.',
  },
  useNextSeoProps() {
    return {
      titleTemplate: '%s - Project Docs',
    };
  },
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta name="description" content="Project documentation" />
    </>
  ),
  primaryHue: 200,
  sidebar: {
    defaultMenuCollapseLevel: 1,
    toggleButton: true,
  },
  toc: {
    float: true,
    title: 'On This Page',
  },
  feedback: {
    content: 'Question? Give us feedback →',
    labels: 'feedback',
  },
  editLink: {
    text: 'Edit this page on GitHub →',
  },
  navigation: {
    prev: true,
    next: true,
  },
};

export default config;

Project Structure

docs/
├── pages/
│   ├── _meta.json              # Root navigation
│   ├── _app.tsx                # Custom App (optional)
│   ├── index.mdx               # Home page (/)
│   ├── getting-started.mdx     # /getting-started
│   ├── concepts/
│   │   ├── _meta.json          # Folder navigation
│   │   ├── index.mdx           # /concepts
│   │   └── architecture.mdx    # /concepts/architecture
│   ├── api/
│   │   ├── _meta.json
│   │   ├── index.mdx
│   │   └── endpoints.mdx
│   └── guides/
│       ├── _meta.json
│       └── quickstart.mdx
├── public/
│   └── images/
├── components/                  # Custom components
│   └── CustomCard.tsx
├── theme.config.tsx
├── next.config.mjs
├── tsconfig.json
└── package.json

Navigation Configuration

Basic _meta.json

{
  "index": "Introduction",
  "getting-started": "Getting Started",
  "concepts": "Core Concepts",
  "api": "API Reference",
  "guides": "Guides"
}

Advanced _meta.json

{
  "index": {
    "title": "Introduction",
    "type": "page",
    "theme": {
      "layout": "full"
    }
  },
  "getting-started": "Getting Started",
  "---": {
    "type": "separator",
    "title": "Features"
  },
  "concepts": {
    "title": "Core Concepts",
    "type": "page"
  },
  "api": {
    "title": "API Reference",
    "type": "menu",
    "items": {
      "endpoints": "Endpoints",
      "authentication": "Authentication"
    }
  },
  "changelog": {
    "title": "Changelog",
    "type": "page",
    "display": "hidden"
  },
  "github": {
    "title": "GitHub",
    "type": "page",
    "href": "https://github.com/org/project",
    "newWindow": true
  }
}

Navigation Item Types

MDX Syntax

Frontmatter

---
title: Page Title
description: SEO description for this page
---

# Page Title

Content starts here...

Basic Markdown

# H1 - Main Title

## H2 - Section

### H3 - Subsection

**Bold text**
*Italic text*
~~Strikethrough~~

- Unordered list
- Another item
  - Nested item

1. Ordered list
2. Second item

[Link text](https://example.com)
[Internal link](/getting-started)

![Image alt text](/images/screenshot.png)

Code Blocks

````mdx

// TypeScript with syntax highlighting
interface User {
  id: string;
  name: string;
}

```typescript filename="src/types/user.ts" // With filename export interface User { id: string; name: string; }

// With line highlighting function example() { const highlighted = true; const normal = false; return { result: true, }; }

// With copy button (enabled by default) const config = { enabled: true };

// With line numbers const line1 = 'first'; const line2 = 'second'; const line3 = 'third';

Built-in Components

Callout

import { Callout } from 'nextra/components';

<Callout type="info">
  This is an informational callout.
</Callout>

<Callout type="warning">
  This is a warning callout.
</Callout>

<Callout type="error">
  This is an error callout.
</Callout>

<Callout emoji="💡">
  Custom emoji callout.
</Callout>

Callout Types:

Tabs

import { Tabs } from 'nextra/components';

<Tabs items={['npm', 'yarn', 'pnpm', 'bun']}>
  <Tabs.Tab>

npm install package-name

  </Tabs.Tab>
  <Tabs.Tab>

yarn add package-name

  </Tabs.Tab>
  <Tabs.Tab>

pnpm add package-name

  </Tabs.Tab>
  <Tabs.Tab>

bun add package-name

  </Tabs.Tab>
</Tabs>

Cards

import { Cards, Card } from 'nextra/components';

<Cards>
  <Card title="Getting Started" href="/getting-started">
    Quick start guide for new users
  </Card>
  <Card title="API Reference" href="/api">
    Complete API documentation
  </Card>
</Cards>

Steps

import { Steps } from 'nextra/components';

<Steps>
### Step 1: Install

Install the package using your package manager.

bun add package-name

### Step 2: Configure

Add configuration to your project.

### Step 3: Use

Import and use in your code.
</Steps>

File Tree

import { FileTree } from 'nextra/components';

<FileTree>
  <FileTree.Folder name="pages" defaultOpen>
    <FileTree.File name="_meta.json" />
    <FileTree.File name="index.mdx" />
    <FileTree.Folder name="api">
      <FileTree.File name="_meta.json" />
      <FileTree.File name="endpoints.mdx" />
    </FileTree.Folder>
  </FileTree.Folder>
  <FileTree.File name="next.config.mjs" />
  <FileTree.File name="theme.config.tsx" />
</FileTree>

Custom Components

Creating Custom Components

// components/FeatureCard.tsx
import { ReactNode } from 'react';

interface FeatureCardProps {
  title: string;
  description: string;
  icon?: ReactNode;
}

export function FeatureCard({ title, description, icon }: FeatureCardProps) {
  return (
    <div className="feature-card p-4 border rounded-lg">
      {icon && <div className="mb-2">{icon}</div>}
      <h3 className="font-semibold">{title}</h3>
      <p className="text-gray-600 dark:text-gray-400">{description}</p>
    </div>
  );
}

Using in MDX

import { FeatureCard } from '../components/FeatureCard';

# Features

<div className="grid grid-cols-2 gap-4">
  <FeatureCard
    title="Fast Builds"
    description="Incremental builds for quick development"
    icon="⚡"
  />
  <FeatureCard
    title="Full-text Search"
    description="Built-in search functionality"
    icon="🔍"
  />
</div>

Styling

Global Styles

/* styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom styles */
.feature-card {
  @apply transition-shadow hover:shadow-lg;
}

Theme Customization

// theme.config.tsx
const config: DocsThemeConfig = {
  primaryHue: {
    dark: 200,
    light: 220,
  },
  // Custom CSS
  head: (
    <>
      <style>{`
        :root {
          --nextra-primary-hue: 220deg;
        }
      `}</style>
    </>
  ),
};

Search Configuration

Built-in Search

Nextra includes Flexsearch by default. No configuration needed.

External Search (Algolia)

// theme.config.tsx
const config: DocsThemeConfig = {
  search: {
    component: function Search() {
      // Custom Algolia DocSearch
      return <AlgoliaSearch />;
    },
  },
};

SEO Configuration

Per-Page SEO

---
title: Getting Started
description: Learn how to get started with Project in 5 minutes
---

# Getting Started

Global SEO

// theme.config.tsx
const config: DocsThemeConfig = {
  useNextSeoProps() {
    return {
      titleTemplate: '%s - Project Documentation',
      defaultTitle: 'Project Documentation',
      description: 'Comprehensive documentation for Project',
      openGraph: {
        type: 'website',
        locale: 'en_US',
        url: 'https://docs.project.com',
        siteName: 'Project Docs',
      },
    };
  },
};

API Documentation

Endpoint Documentation Pattern

````mdx

Create User

Create a new user account.

Endpoint

POST /api/v1/users

Authentication

Requires Bearer token.

Request Body

Example Request

curl -X POST https://api.project.com/v1/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "name": "John", "password": "secure123"}'

Response

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John",
  "createdAt": "2024-01-15T12:00:00Z"
}

Error Responses

````

Documentation Checklist

Content

• [ ] Clear, descriptive title
• [ ] One-sentence summary
• [ ] Proper heading hierarchy (H1 → H2 → H3)
• [ ] Consistent terminology
• [ ] Technical accuracy verified

Structure

• [ ] _meta.json configured
• [ ] Logical flow (overview → details → examples)
• [ ] Quick start near top
• [ ] Related links at end

Code

• [ ] Language specified on all code blocks
• [ ] Examples are complete and runnable
• [ ] Copy button enabled for commands
• [ ] Line highlighting for key lines

SEO

• [ ] Title in frontmatter
• [ ] Description in frontmatter
• [ ] Internal linking strategy
• [ ] Alt text for images

Building and Deployment

Development

# Start dev server
bun run dev

# Build for production
bun run build

# Start production server
bun run start

Deployment

# Vercel (recommended)
vercel

# Static export
# In next.config.mjs:
# output: 'export'
bun run build

Deployment Checklist

• [ ] All links tested
• [ ] Images optimized
• [ ] Search working
• [ ] Mobile responsive
• [ ] SEO meta tags present
• [ ] Analytics configured

Migration from Docusaurus