Blog

Comment utiliser Nextra Docs et le déployer sur Vercel : Guide étape par étape

Ashley Goolam

Ashley Goolam

12 June 2025

Comment utiliser Nextra Docs et le déployer sur Vercel : Guide étape par étape

Si vous souhaitez créer un site web de documentation élégant et moderne en toute simplicité, Nextra Docs est l'un des meilleurs outils disponibles. Construit sur Next.js, Nextra vous permet d'écrire votre documentation en Markdown ou MDX, de personnaliser l'apparence et la convivialité, et de la déployer sans effort, surtout sur Vercel. Dans cet article, nous allons vous guider pas à pas pour configurer un site Nextra Docs à partir de zéro et le déployer gratuitement sur Vercel.

💡
Vous cherchez un excellent outil de test d'API qui génère de belles documentations d'API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et remplace Postman à un prix beaucoup plus abordable !
button

Qu'est-ce que Nextra Docs ? Votre meilleur ami pour créer de la documentation

Nextra docs est un framework basé sur Next.js qui facilite grandement la création de sites de documentation. Tout tourne autour du contenu Markdown (ou MDX) avec un thème Docs pré-construit qui intègre la navigation, la recherche et une table des matières prêts à l'emploi. Voici pourquoi nextra docs est génial :

Les utilisateurs s'enthousiasment pour nextra docs en raison de sa "finition sans configuration" et de ses déploiements Vercel. Prêt à construire votre site ? Plongeons-y !

Pourquoi utiliser Nextra Docs avec Vercel ?

Nextra docs est parfait pour les développeurs, les startups ou les projets open source ayant besoin d'une documentation professionnelle rapidement. L'associer à Vercel, le terrain de jeu de Next.js, signifie :

J'ai déployé un site de test sur Vercel, et il était en ligne en moins de 5 minutes, aussi fluide que du beurre !

Comment configurer Nextra Docs : Guide étape par étape

Créons un site nextra docs à partir de zéro en utilisant le routeur d'application de Next.js. Suivez les étapes, et vous aurez un site local fonctionnel en ~20 minutes !

1. Créer un nouveau projet Next.js

npx create-next-app my-nextra-docs
options du projet next js
cd my-nextra-docs

2. Installer les dépendances Nextra Docs

Installez les packages de base pour nextra docs :

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

3. Mettre à jour les scripts package.json

Assurez-vous que package.json inclut ces scripts (ils sont généralement ajoutés par create-next-app) :

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

"dev": "next --turbopack"
package.json
npm run dev

Visitez http://localhost:3000 pour confirmer que l'application Next.js fonctionne.

page d'accueil next js

Moche :( Mais bon, ça marche ! Maintenant, essayons de corriger ça.

4. Configurer Nextra Docs

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. Configurer les composants MDX

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. Mettre à jour la mise en page de l'application

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Ajouter des pages de documentation

message d'erreur 404 sur la page d'accueil
/app/resources
  /page.mdx

Pour des tests, j'ai ajouté :

# Resources

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favourite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Comand Line](https://github.co./jlevy/the-art-of-command-line)

Mais le contenu n'a pas besoin d'être complexe et peut être aussi simple que :

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site:)

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in
page d'accueil nextra

Allez-y, modifiez cette page, ajoutez-en d'autres, et essayez toutes les fonctionnalités comme le mode sombre/clair. Le pouvoir est entre vos mains, et les options sont infinies !

mode clair et sombre

Déployer Nextra Docs sur Vercel

Maintenant, mettons votre site nextra docs en ligne sur Vercel, c'est super facile puisque Vercel est conçu pour Next.js.

8. Pousser votre code sur GitHub

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

9. Déployer sur Vercel

vercel

Personnaliser votre site Nextra Docs

Envie de donner du peps à votre site nextra docs ? Essayez ceci :

J'ai ajouté un composant d'encadré personnalisé à ma documentation, ça avait l'air pro en 10 minutes !

Dépannage et astuces pour Nextra Docs

exemple de documentation nextra personnalisée

Pourquoi Nextra Docs et Vercel forment une paire parfaite

Nextra docs rend la documentation amusante avec sa simplicité Markdown et la vitesse de Next.js. Les déploiements en un clic de Vercel et l'hébergement gratuit scellent l'affaire. Bien sûr, le routeur d'application pourrait dérouter les novices de Next.js, mais la documentation Nextra est solide. Comparé à Docusaurus, nextra docs semble plus léger et plus moderne.

Prêt à lancer votre documentation ? Construisez votre site nextra docs et déployez-le sur Vercel, j'ai hâte de voir votre création ! Et n'oubliez pas de jeter un œil à Apidog.

💡
Vous cherchez un excellent outil de test d'API qui génère de belles documentations d'API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et remplace Postman à un prix beaucoup plus abordable !
button

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger