Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra supports fully static HTML export, allowing you to build your documentation site as a set of pre-rendered HTML, CSS, and JavaScript files with no Node.js server required at runtime. Static exports are ideal for hosting on platforms like GitHub Pages, Nginx, Cloudflare Pages, or any static CDN — you get the full authoring experience of Nextra with the simplicity of static file hosting.

​
Getting Started

1
Configure static export in next.config.mjs
2
Add output: 'export' to your Next.js config and set images to unoptimized mode (required because Next.js image optimization needs a server):
3
import nextra from 'nextra'

const withNextra = nextra({
  // ... Nextra-specific options
})

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true // required for static export
  }
  // Optional: change the output directory from 'out' to something else
  // distDir: 'dist'
}

export default withNextra(nextConfig)
4
images: { unoptimized: true } is mandatory for static exports. Without it, Next.js will throw a build error because the image optimization API requires a running server.
5
Update the Pagefind postbuild script
6
Nextra’s Pagefind search integration indexes your built pages. For static exports, point the Pagefind command at the .next/server/app directory where Next.js writes the pre-rendered HTML, and write the index to out/_pagefind:
7
{
  "scripts": {
    "build": "next build",
    "postbuild": "pagefind --site .next/server/app --output-path out/_pagefind"
  }
}
8
The postbuild script runs automatically after next build completes. It scans the server-rendered HTML and writes the search index into the static output directory.
9
If you changed the output directory via distDir in your Next.js config, update the --output-path argument to match — for example, pagefind --site .next/server/app --output-path dist/_pagefind.
10
Build your site
11
Run the build command for your package manager. The static site will be written to the out/ directory by default:
12
npm
npm run build
pnpm
pnpm run build
yarn
yarn build
13
After the build completes, the out/ directory contains everything needed to serve your site — copy it to any static host.

​
Deploying the Static Output

Once built, the out/ directory is a self-contained static site. Deploy it to any static hosting platform:
Push the contents of out/ to the gh-pages branch, or configure GitHub Actions to deploy on every push to main. Set the GitHub Pages source to the gh-pages branch in your repository settings.
.github/workflows/deploy.yml
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./out

​
What Works with Static Export

Most of Nextra’s features work fully with static export:
  • All MDX content with full syntax highlighting (rehype-pretty-code / Shiki)
  • Nextra components: <Callout>, <Tabs>, <Steps>, <FileTree>, etc.
  • nextra-theme-docs and nextra-theme-blog themes
  • Pagefind full-text search (via postbuild script)
  • Dark mode toggle
  • Table of contents
  • Sidebar navigation generated from _meta files
  • Static images (with unoptimized: true)
  • Internationalization (i18n) with static locale pages
  • Custom app/ routes alongside MDX pages
Static export removes all server-side runtime capabilities. The following features require a running Node.js server and will not work with output: 'export':
  • Next.js Image Optimization — use unoptimized: true as a workaround
  • Server Actions — these require a server to execute
  • Route Handlers that run at request time (API routes)
  • Middleware — runs at the edge, not available in static output
  • Incremental Static Regeneration (ISR) — no server to revalidate pages
  • Dynamic server-side rendering (force-dynamic pages)
For more detail, see the Next.js static export limitations documentation.

​
Configuration Reference

next.config.mjs
import nextra from 'nextra'

const withNextra = nextra({
  // Nextra options work the same as with server deployments
  defaultShowCopyCode: true,
  latex: true
})

export default withNextra({
  output: 'export',

  images: {
    unoptimized: true // required
  },

  // Optional: use a different output directory name
  // distDir: 'dist',

  // Optional: add a base path if deploying to a subdirectory
  // basePath: '/my-docs',

  // Optional: add asset prefix for CDN deployment
  // assetPrefix: 'https://cdn.example.com'
})
If you set basePath for subdirectory deployments (e.g., basePath: '/docs'), make sure to also update your Pagefind command and any hardcoded links in your content accordingly.

Build docs developers (and LLMs) love

Get started for freeTalk to us