nextra-theme-docs-v3

A modern documentation site theme for Nextra built with Tailwind CSS v3

Overview

nextra-theme-docs-v3 is a standalone documentation theme that provides everything you need to build a modern, beautiful documentation website. It's a fork of the official nextra-theme-docs adapted to use Tailwind CSS v3 instead of v4, making it compatible with projects that haven't migrated to Tailwind v4.

Features

Responsive Design - Mobile-first, fully responsive layout
Dark Mode - Built-in dark mode with system preference detection
Search - Integrated search functionality
Navigation - Automatic table of contents, sidebar, and pagination
Internationalization - Full i18n support with locale switching
Customizable - Extensive theme configuration options
GitHub Integration - Edit links, feedback links, and issue tracking
Performance - Optimized for performance with Tailwind CSS v3
Accessibility - WCAG compliant with proper semantic HTML

Components Included

Top navigation bar with logo and menu
Collapsible sidebar with page tree
Table of contents (TOC) with scroll spy
Previous/next page navigation
Theme switcher (light/dark/system)
Locale switcher for i18n
"Edit this page" link
"Feedback" link
Last updated timestamp
Back to top button
Banner component for announcements
Custom footer support

Quick Start

Installation

Create a new Next.js project and install the required dependencies:

# Create a new Next.js app
npx create-next-app@latest my-docs

cd my-docs

# Install Nextra and the theme
npm install nextra nextra-theme-docs-v3

Note: If you already have a Next.js project, you only need to install nextra and nextra-theme-docs-v3.

Configure Next.js

Create or update next.config.mjs:

import nextra from "nextra";

const withNextra = nextra({
  theme: "nextra-theme-docs-v3",
  themeConfig: "./theme.config.jsx",
});

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

Configure Package Scripts

Add the following scripts to your package.json:

{
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}

Create Root Layout

Create app/layout.jsx:

import { Footer, Layout, Navbar } from "nextra-theme-docs-v3";
import { Banner, Head } from "nextra/components";
import { getPageMap } from "nextra/page-map";
import "nextra-theme-docs-v3/style.css";

export const metadata = {
  title: "My Documentation",
  description: "Documentation built with Nextra and Tailwind CSS v3",
};

const banner = <Banner storageKey="banner">Nextra v3 is released!</Banner>;
const navbar = (
  <Navbar
    logo={<b>My Docs</b>}
    projectLink="https://github.com/yourusername/your-repo"
  />
);
const footer = <Footer>MIT {new Date().getFullYear()} © My Docs.</Footer>;

export default async function RootLayout({ children }) {
  return (
    <html lang="en" dir="ltr" suppressHydrationWarning>
      <Head>{/* Your additional head tags */}</Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/yourusername/your-repo/tree/main"
          footer={footer}
        >
          {children}
        </Layout>
      </body>
    </html>
  );
}

Create MDX Components

Create mdx-components.jsx:

import { useMDXComponents } from "nextra-theme-docs-v3";

export function useMDXComponents(components) {
  return useMDXComponents(components);
}

Create Content

Create app/page.mdx:

# Welcome to My Documentation

This is my first documentation page built with [Nextra](https://nextra.site) and Tailwind CSS v3!

## Features

- Easy to use
- Fast and responsive
- Beautiful out of the box

Run Development Server

npm run dev

Visit http://localhost:3000 to see your documentation site!

Theme Configuration

The theme is configured through the <Layout> component props in your root layout.

Core Props

Prop	Type	Default	Description
`pageMap`	`PageMapItem[]`	required	Page map from `getPageMap()`
`docsRepositoryBase`	`string`	`"https://github.com/shuding/nextra"`	Docs repository URL
`children`	`ReactNode`	required	Page content

Layout Components

Banner

import { Banner } from "nextra/components";

const banner = <Banner storageKey="my-banner">Important announcement!</Banner>;

Prop	Type	Description
`storageKey`	`string`	localStorage key for dismissal
`children`	`ReactNode`	Banner content

Navbar

import { Navbar } from "nextra-theme-docs-v3";

const navbar = (
  <Navbar
    logo={<b>My Logo</b>}
    projectLink="https://github.com/user/repo"
    chatLink="https://discord.gg/..."
  />
);

Prop	Type	Description
`logo`	`ReactNode`	Logo or brand name
`projectLink`	`string`	GitHub repository URL
`chatLink`	`string`	Discord or chat link
`feedbackComponent`	`ReactNode`	Custom feedback component

Footer

import { Footer } from "nextra-theme-docs-v3";

const footer = <Footer>MIT © 2024</Footer>;

Navigation Options

Sidebar

<Layout
  sidebar={{
    defaultOpen: true,
    toggleButton: true,
    defaultMenuCollapseLevel: 2,
    autoCollapse: false,
  }}
>
  {children}
</Layout>

Option	Type	Default	Description
`defaultOpen`	`boolean`	`true`	Show sidebar by default
`toggleButton`	`boolean`	`true`	Show sidebar toggle button
`defaultMenuCollapseLevel`	`number`	`2`	Folder collapse level (1 = all collapsed)
`autoCollapse`	`boolean`	`false`	Auto-collapse inactive folders

Page Navigation

<Layout
  navigation={{
    prev: true,
    next: true,
  }}
>
  {children}
</Layout>

Option	Type	Default	Description
`prev`	`boolean`	`true`	Show previous page link
`next`	`boolean`	`true`	Show next page link

Theme & Styling

Dark Mode

<Layout
  darkMode={true}
  nextThemes={{
    defaultTheme: "system",
    storageKey: "theme",
    disableTransitionOnChange: true,
  }}
>
  {children}
</Layout>

Option	Type	Default	Description
`darkMode`	`boolean`	`true`	Enable dark mode toggle
`nextThemes.defaultTheme`	`string`	`'system'`	Default theme ('light', 'dark', 'system')
`nextThemes.storageKey`	`string`	`'theme'`	localStorage key
`nextThemes.disableTransitionOnChange`	`boolean`	`true`	Disable transitions on theme change

Theme Switch Labels

<Layout
  themeSwitch={{
    dark: "Dark",
    light: "Light",
    system: "System",
  }}
>
  {children}
</Layout>

Git Integration

Edit Link

<Layout
  editLink="Edit this page"
  // or disable: editLink={null}
>
  {children}
</Layout>

Feedback Link

<Layout
  feedback={{
    content: "Question? Give us feedback",
    labels: "feedback",
    link: "https://github.com/user/repo/issues/new",
  }}
>
  {children}
</Layout>

Option	Type	Default	Description
`content`	`ReactNode`	`'Question? Give us feedback'`	Link text
`labels`	`string`	`'feedback'`	GitHub issue labels
`link`	`string`	auto-generated	Custom feedback URL

Last Updated

import { LastUpdated } from "nextra-theme-docs-v3";

<Layout lastUpdated={<LastUpdated locale="en">Last updated:</LastUpdated>}>
  {children}
</Layout>;

Internationalization

<Layout
  i18n={[
    { locale: "en", name: "English" },
    { locale: "es", name: "Español" },
    { locale: "fr", name: "Français" },
  ]}
>
  {children}
</Layout>

Search

import { Search } from "nextra/components";

<Layout
  search={<Search />}
  // or disable: search={null}
>
  {children}
</Layout>;

For advanced search setup, see the Nextra Search Documentation.

Page Configuration

Front Matter

Configure individual pages using MDX front matter:

---
title: Page Title
description: Page description for SEO
sidebarTitle: Custom Sidebar Title
---

# Page Content

Meta Files

Create _meta.js files to organize your documentation:

// app/docs/_meta.js
export default {
  index: "Introduction",
  "getting-started": "Getting Started",
  guides: {
    title: "Guides",
    items: {
      installation: "Installation",
      configuration: "Configuration",
    },
  },
  "--": {
    type: "separator",
    title: "Advanced",
  },
  api: "API Reference",
};

Customization

Custom CSS

Create a global CSS file and import it in your layout:

/* styles/globals.css */
:root {
  --nextra-primary-hue: 212;
  --nextra-primary-saturation: 100%;
  --nextra-primary-lightness: 53%;
}

// app/layout.jsx
import "../styles/globals.css";

Custom Components

Create custom MDX components in mdx-components.jsx:

import { useMDXComponents } from "nextra-theme-docs-v3";

const components = {
  // Override or add components
  h1: ({ children }) => <h1 className="text-4xl font-bold my-4">{children}</h1>,
};

export function useMDXComponents(providerComponents) {
  return useMDXComponents({
    ...providerComponents,
    ...components,
  });
}

API

Hooks

`useConfig()`

Access current page configuration:

import { useConfig } from "nextra-theme-docs-v3";

function MyComponent() {
  const { title, frontMatter } = useConfig();
  return <div>{title}</div>;
}

`useThemeConfig()`

Access theme configuration:

import { useThemeConfig } from "nextra-theme-docs-v3";

function MyComponent() {
  const config = useThemeConfig();
  return <div>{config.docsRepositoryBase}</div>;
}

`useMenu()`

Access and control sidebar menu state:

import { useMenu, setMenu } from "nextra-theme-docs-v3";

function MyComponent() {
  const menu = useMenu();
  const toggle = () => setMenu(!menu);
  return <button onClick={toggle}>Toggle Menu</button>;
}

Components

Available for import:

import {
  Layout,
  Navbar,
  Footer,
  ThemeSwitch,
  LocaleSwitch,
  LastUpdated,
  NotFoundPage,
  Link,
} from "nextra-theme-docs-v3";

Migration from nextra-theme-docs

If you're migrating from the official nextra-theme-docs (Tailwind v4) to this v3 version:

Update package installation:

npm uninstall nextra-theme-docs
npm install nextra-theme-docs-v3

Update imports:

// Before
import { Layout } from "nextra-theme-docs";
import "nextra-theme-docs/style.css";

// After
import { Layout } from "nextra-theme-docs-v3";
import "nextra-theme-docs-v3/style.css";

Update Next.js config:

// Before
const withNextra = nextra({
  theme: "nextra-theme-docs",
  // ...
});

// After
const withNextra = nextra({
  theme: "nextra-theme-docs-v3",
  // ...
});

No configuration changes needed - All props and options remain the same!

TypeScript Support

The package includes full TypeScript definitions:

import type {
  LayoutProps,
  ThemeConfig,
  PageMapItem,
} from "nextra-theme-docs-v3";

Examples

See the Nextra documentation for a live example built with this theme.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Acknowledgments

Based on nextra-theme-docs by Shu Ding
Built with Nextra and Tailwind CSS v3

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
css		css
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PLAN.md		PLAN.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.mts		vitest.config.mts

Option	Type	Default	Description
`float`	`boolean`	`true`	Float TOC next to content
`title`	`ReactNode`	`'On This Page'`	TOC section title
`backToTop`	`ReactNode`	`'Scroll to top'`	Back to top button text
`extraContent`	`ReactNode`	-	Extra content below TOC

License

eekrain/nextra-theme-docs-v3

Folders and files

Latest commit

History

Repository files navigation

nextra-theme-docs-v3

Overview

Features

Components Included

Quick Start

Installation

Configure Next.js

Configure Package Scripts

Create Root Layout

Create MDX Components

Create Content

Run Development Server

Theme Configuration

Core Props

Layout Components

Banner

Navbar

Footer

Navigation Options

Sidebar

Table of Contents

Page Navigation

Theme & Styling

Dark Mode

Theme Switch Labels

Git Integration

Edit Link

Feedback Link

Last Updated

Internationalization

Search

Page Configuration

Front Matter

Meta Files

Customization

Custom CSS

Custom Components

API

Hooks

useConfig()

useThemeConfig()

useMenu()

Components

Migration from nextra-theme-docs

TypeScript Support

Examples

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`useConfig()`

`useThemeConfig()`

`useMenu()`

Packages