Nextra : une documentation Next.js à partir de Markdown

Ce blog tourne sur Next.js et des fichiers MDX. Le lecteur ne voit pas tout ce qu'il a fallu écrire à la main : la lecture des fichiers, le frontmatter, la liste des articles, les métadonnées, la coloration du code. Pour un blog, c'est raisonnable. Pour une documentation de cinquante pages avec une barre latérale, une recherche et une table des matières, ce serait refaire un outil qui existe déjà.

Cet outil, c'est Nextra. C'est un framework open source qui transforme un dossier de fichiers Markdown et MDX en site Next.js. La navigation se déduit de l'arborescence, la recherche est intégrée, chaque page reçoit sa table des matières. Et comme le résultat reste une application Next.js, on peut y mettre n'importe quel composant React.

Le projet

Nextra a été créé en 2020 par Shu Ding, développeur chez Vercel et co-auteur de la bibliothèque SWR. Il est aujourd'hui maintenu surtout par Dimitri Postolov, de The Guild, l'équipe derrière GraphQL Yoga et GraphQL Mesh. Le dépôt shuding/nextra compte près de 14 000 étoiles en octobre 2026, sous licence MIT, écrit en TypeScript.

Il sert de base à des documentations connues : celle de SWR et celles de la plupart des projets de The Guild. Le site officiel, nextra.site, est lui-même construit avec Nextra.

Ce que fait la version 4

La version 4, sortie le 13 janvier 2025, a été une réécriture plus qu'une mise à jour. Elle abandonne le Pages Router pour l'App Router de Next.js, et avec lui le fichier theme.config.jsx des versions précédentes. La configuration du thème passe désormais par des composants React dans le layout.

Deux thèmes officiels existent : nextra-theme-docs pour une documentation, nextra-theme-blog pour un blog. On peut aussi écrire son propre thème à partir de la carte des pages que Nextra génère.

Installer une documentation

Dans un projet Next.js, ou dans un dossier vide :

npm i next react react-dom nextra nextra-theme-docs

La configuration Next.js passe par la fonction nextra :

import nextra from 'nextra'
 
const withNextra = nextra({
  contentDirBasePath: '/docs'
})
 
export default withNextra({
  reactStrictMode: true
})

Le thème demande un fichier mdx-components.js à la racine :

import { useMDXComponents as getDocsMDXComponents } from 'nextra-theme-docs'
 
const docsComponents = getDocsMDXComponents()
 
export const useMDXComponents = components => ({
  ...docsComponents,
  ...components
})

Puis un layout qui monte le thème :

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export default async function RootLayout({ children }) {
  return (
    <html lang="fr" dir="ltr" suppressHydrationWarning>
      <Head />
      <body>
        <Layout
          navbar={<Navbar logo={<b>Ma doc</b>} />}
          footer={<Footer>MIT {new Date().getFullYear()}</Footer>}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/moi/mon-projet/tree/main"
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

getPageMap() est la pièce centrale. Nextra parcourt les fichiers de contenu et construit l'arbre des routes, avec titres et ordre. Le thème s'en sert pour dessiner la barre latérale, la navigation du haut et les liens « page précédente, page suivante ».

Deux façons de ranger le contenu

La première suit la convention de l'App Router : chaque page est un page.mdx dans app/. C'est cohérent avec Next.js, mais on se retrouve avec cinquante fichiers qui portent tous le même nom.

La seconde, que je préfère, utilise le dossier content :

app/
├── layout.jsx
└── docs/
    └── [[...mdxPath]]/
        └── page.jsx
content/
├── _meta.js
├── index.mdx
├── installation.mdx
└── guide/
    ├── _meta.js
    ├── configuration.mdx
    └── deploiement.mdx

Une seule route attrape-tout, [[...mdxPath]], sert tous les fichiers du dossier. Son code tient en vingt lignes et se copie depuis l'exemple officiel. Le rechargement à chaud fonctionne sans dépendance supplémentaire, et migrer une ancienne doc Nextra 3 revient presque à renommer pages en content.

L'ordre et les titres avec _meta

Par défaut, les pages apparaissent par ordre alphabétique, avec un titre déduit du nom de fichier. Un _meta.js dans chaque dossier corrige ça :

export default {
  index: 'Introduction',
  installation: 'Installation',
  guide: 'Guide',
  '---': {
    type: 'separator'
  },
  changelog: {
    title: 'Changelog',
    type: 'page'
  }
}

L'ordre des clés donne l'ordre de la barre latérale. type: 'page' place l'entrée dans la barre du haut au lieu de la barre latérale, ce qui permet d'avoir plusieurs « sous-documentations » sur un même site. En TypeScript, le type MetaRecord exporté par nextra vérifie la structure.

La recherche sans serveur

Nextra 4 a remplacé FlexSearch par Pagefind. Pagefind indexe les pages HTML après le build et produit des fichiers statiques que le navigateur interroge directement. Pas d'Algolia, pas de compte, pas de clé d'API.

npm i -D pagefind

{
  "scripts": {
    "build": "next build",
    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind"
  }
}

Le dossier public/_pagefind va dans le .gitignore. Contrepartie : la recherche ne fonctionne pas en next dev, il faut un build pour la tester.

MDX, et tout ce que React permet

L'intérêt de Nextra face à un générateur Markdown pur, c'est MDX. Une page peut importer un composant React et l'utiliser au milieu du texte :

import { Callout, Steps, Tabs } from 'nextra/components'
 
# Installation
 
<Callout type="warning">
  Node.js 20 ou plus est requis.
</Callout>
 
<Tabs items={['npm', 'pnpm']}>
  <Tabs.Tab>`npm i mon-paquet`</Tabs.Tab>
  <Tabs.Tab>`pnpm add mon-paquet`</Tabs.Tab>
</Tabs>

Nextra fournit les composants qu'on attend d'une doc : Callout, Steps, Tabs, Cards, FileTree. Il gère aussi la coloration avec Shiki, les formules LaTeX, les diagrammes Mermaid, l'internationalisation, et génère la documentation d'une API TypeScript à partir des commentaires TSDoc. Pour une bibliothèque React, on peut afficher une démo interactive du composant directement dans la page qui le décrit.

Puisque c'est du Next.js, les métadonnées, le sitemap et les balises Open Graph suivent les mêmes règles que dans le guide SEO de Next.js. Le frontmatter title et description de chaque page alimente directement les métadonnées.

Le point de vigilance : la maintenance

C'est ce qu'il faut regarder avant de s'engager. En octobre 2026, la dernière version publiée sur npm est la 4.6.1, du 4 décembre 2025. Le dépôt contient pourtant des correctifs numérotés jusqu'à 4.6.5, dont un sur la recherche avec basePath et un autre qui faisait passer un build de 2 secondes à 3 minutes dans un worktree git. Ils n'ont pas été publiés. Le dernier commit sur main date de juin 2026, et une branche de version 5 est restée en alpha depuis l'été 2025.

Le projet n'est pas abandonné, mais il avance lentement, porté par une poignée de mainteneurs. Pour une doc qui marche aujourd'hui, ça ne change rien : Nextra 4.6.1 fonctionne avec Next.js 16. Pour un projet qui dépendra de corrections rapides, c'est à savoir.

Nextra, VitePress ou Docusaurus ?

VitePress et sa documentation technique reste mon premier choix pour documenter un projet sans contexte particulier : plus rapide à démarrer, plus léger, très actif. Docusaurus garde l'avantage pour une API qui doit documenter plusieurs versions en parallèle.

Nextra prend l'avantage quand l'équipe vit déjà dans Next.js. La doc peut partager les composants du produit, son système de design, son déploiement, et même vivre dans le même dépôt sous /docs. Si vous hésitez encore sur le framework de base, le comparatif des méta-frameworks Vue et React aide à trancher en amont.

Nextra fait exactement ce qu'on attend de lui : écrire du Markdown et obtenir une doc propre, sans quitter l'écosystème Next.js. La version 4 est solide et moderne. Ce qui me fait hésiter, ce n'est pas le code, c'est le rythme : des correctifs prêts mais non publiés, c'est le signe d'un projet qui manque de bras. Pour une équipe déjà sur Next.js, je le choisirais quand même, en épinglant la version. Pour partir de zéro, je regarderais d'abord VitePress.