Documentation Website Development on Nextra (Next.js)

Building a Documentation Site with Nextra (Next.js Documentation)

Nextra is a documentation framework built on top of Next.js by the Vercel team. It uses MDX, supports App Router, and works out-of-the-box on Vercel. Unlike Docusaurus, it's a full Next.js application—you can add API routes, SSR pages, and any Next.js features.

Initialization

npx create-next-app@latest my-docs --typescript --tailwind --app
npm install nextra nextra-theme-docs

next.config.ts

import nextra from 'nextra';

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

export default withNextra({
  reactStrictMode: true,
  images: {
    remotePatterns: [{ hostname: 'images.unsplash.com' }],
  },
});

theme.config.tsx

import { DocsThemeConfig } from 'nextra-theme-docs';
import React from 'react';

const config: DocsThemeConfig = {
  logo: (
    <span style={{ fontWeight: 700 }}>My Project</span>
  ),
  project: { link: 'https://github.com/my-org/my-project' },
  docsRepositoryBase: 'https://github.com/my-org/my-project/blob/main/docs',
  footer: {
    text: `© ${new Date().getFullYear()} My Company`,
  },
  useNextSeoProps() {
    return {
      titleTemplate: '%s – My Project',
    };
  },
  primaryHue: { dark: 210, light: 212 },
  navigation: { prev: true, next: true },
  toc: {
    backToTop: true,
    float: true,
  },
  editLink: { text: 'Edit this page on GitHub' },
  feedback: { content: 'Question? Give us feedback →' },
  sidebar: {
    titleComponent: ({ title, type }) => (
      type === 'separator' ? (
        <span style={{ textTransform: 'uppercase', fontSize: '11px', fontWeight: 600 }}>
          {title}
        </span>
      ) : <>{title}</>
    ),
    defaultMenuCollapseLevel: 1,
    autoCollapse: true,
  },
};

export default config;

File Structure

app/
├── layout.tsx
└── [[...mdxPath]]/
    └── page.tsx        # catch-all for MDX files

content/
├── _meta.json          # navigation order and titles
├── index.mdx           # home page
├── guide/
│   ├── _meta.json
│   ├── installation.mdx
│   └── configuration.mdx
└── api/
    ├── _meta.json
    └── reference.mdx

// content/_meta.json
{
  "index": "Introduction",
  "guide": {
    "title": "Guide",
    "type": "folder"
  },
  "api": {
    "title": "API Reference",
    "type": "folder"
  },
  "changelog": "Changelog",
  "---": { "type": "separator" },
  "github_link": {
    "title": "GitHub ↗",
    "href": "https://github.com/my-org/my-project",
    "newWindow": true
  }
}

MDX with React Components

---
title: API Reference
---

import { Callout, Tabs, Tab } from 'nextra/components';

# API Reference

<Callout type="warning">
  Breaking change in v2.0: the `apiKey` parameter was renamed to `key`.
</Callout>

<Tabs items={['cURL', 'JavaScript', 'Python']}>
  <Tab>
    ```bash
    curl https://api.myproject.com/v1/users \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
  <Tab>
    ```ts
    const users = await client.users.list();
    ```
  </Tab>
  <Tab>
    ```python
    users = client.users.list()
    ```
  </Tab>
</Tabs>

Deployment on Vercel

vercel --prod
# Nextra is automatically optimized for Vercel Edge Network

Setting up a Nextra documentation site takes 2–3 days.