Nextra vous permet de créer un site en quelques minutes, il est donc parfait pour distribuer des documents à votre équipe.

Si vous connaissez Next.js, vous pouvez l'utiliser pour développer facilement un site de documentation. Le framework Nextra s'occupe des choses sérieuses pour vous; tout ce que vous avez à faire est d'ajouter du contenu Markdown ou HTML et des données YAML ou JSON.

Parcourez ces étapes pour créer un site de documentation à l'aide de Nextra, un générateur de site statique basé sur Next.js. Vous installerez et configurerez les dépendances nécessaires, puis apprendrez à ajouter de nouveaux documents et pages, à écrire Markdown et à inclure des composants React.

Exigences pour créer un site de documentation avec Nextra

Commencez par installer Node.js si vous ne l'avez pas déjà fait. Le dernière version de Node.js est livré avec npm, le gestionnaire de packages de nœuds, dont vous aurez besoin pour installer les dépendances pour ce projet.

En plus de Node.js, vous devrez installer

Gite. Vous avez besoin de Git pour déployer le site sur les pages GitHub, Netlify ou un autre fournisseur d'hébergement. Vous aurez également besoin d'un éditeur de code avancé, tel que VS Code.

Installation de Nextra

Vous pouvez utiliser un modèle de documentation nextra pour démarrer un site de documentation. Lancez une invite de commande et accédez au répertoire dans lequel vous souhaitez configurer votre projet. Exécutez ensuite la commande suivante pour démarrer le site de documentation :

clone git https://github.com/shuding/nextra-docs-template

Cette commande échafaudera une application dans le répertoire courant. Ensuite, exécutez la commande suivante pour installer les dépendances :

cd nextra-docs-template
installation npm

Une fois l'installation terminée, lancez l'application. Faites-le en exécutant la commande suivante sur votre terminal :

npm run dev

Cette commande démarre un serveur de développement sur localhost: 3000. Suivez le lien sur votre terminal pour consulter le site de documentation. La page d'accueil devrait ressembler à ceci :

Si vous regardez sur le côté gauche de la page, vous trouverez les pages nommées Introduction et Une autre page. Sous ces liens de page, vous trouverez une page nommée Satori, imbriquée dans le Avancé (un dossier) annuaire. Enfin, dans la zone de navigation, vous trouverez des liens vers les À propos et Contact pages.

Pour comprendre le fonctionnement de ces pages, vous devez d'abord comprendre comment Next.js rend les pages.

Comprendre la structure du répertoire

Étant donné que Nextra utilise le framework Next.js, il rend chaque fichier dans le page/ dossier sur une page distincte.

À l'intérieur de pages répertoire, vous trouverez quatre fichiers modèles: about.mdx, avancé.mdx, un autre.mdx, et index.mdx. Chacun de ces fichiers correspond à une page du site Internet; Par exemple, index.mdx correspond à la page d'accueil. L'URL hôte local: 3000/environ Correspond à about.mdx, et ainsi de suite.

À l'intérieur pages, il existe également un dossier nommé avancé, contenant un seul fichier nommé satori.mdx. L'URL de ce fichier sera localhost: 3000/avancé/satori.

Remarquez comment chacun de ces fichiers se termine par un .mdx extension.

Qu'est-ce que MDX?

Si tu as expérience avec React, vous devez connaître JSX. Il s'agit d'un langage de type HTML que vous pouvez utiliser pour décrire l'interface utilisateur des composants React.

MDX charge, analyse et restitue JSX dans un document Markdown. Grâce à MDX, vous pouvez écrire des composants React et les importer dans vos documents Markdown si nécessaire. Les fichiers MDX se terminent par l'extension .mdx et peuvent inclure à la fois Markdown et JSX.

MDX vous permet de combiner vos connaissances de Markdown avec React pour créer des composants réutilisables. Tu peux créer des modules CSS pour styliser les composants. Cela vous aide à organiser vos composants pour améliorer la lisibilité et la maintenabilité.

Comment modifier des pages existantes dans le site de documentation

Pour modifier une page existante, il suffit d'ouvrir le fichier correspondant et d'y apporter des modifications. Les langages pris en charge sont Markdown et JSX.

Par exemple, ouvrez le index.mdx fichier et remplacez le contenu par ceci :

# Bienvenue dans ma documentation
Je suis heureux de vous voir ici. Merci
## Mes réseaux sociaux
Suivez-moi sur [Twitter](https://twitter.com/kingchuuks) et [LinkedIn](https://linkedin.com/in/kingchuks)

Cet exemple utilise Markdown pour formater le contenu. Il contient un titre de niveau un, un titre de niveau deux et deux liens de médias sociaux.

Enregistrez le fichier et visitez la page d'accueil de votre site de documentation. La page devrait maintenant ressembler à ceci :

En bas de la page, vous pouvez également trouver la date de la dernière mise à jour du document.

Ajouter une nouvelle page

Avant d'ajouter une nouvelle page, vous devez d'abord décider si la page sera dans le page/ répertoire ou à l'intérieur d'un dossier qu'il contient. Utilisez des dossiers si vous souhaitez catégoriser vos pages ou développer une hiérarchie.

Dans ce cas, créez une page autonome au niveau supérieur. Ouvrir un fichier nommé installation.mdx dans votre éditeur de code et collez-y le code Markdown suivant :

# Guide d'installation
Suivez ce guide pour installer mon package dans votre projet
## 1. Installer Node.js
Pour installer Node.js, visitez le
[Site de documentation Node.js](https://nodejs.org/en/download)

Enregistrez le fichier et vérifiez le navigateur. Vous trouverez l'étiquette d'installation dans le menu latéral. Lorsque vous cliquez sur le lien, le contenu de installation.mdx s'affiche sur la page :

Vous pouvez modifier le libellé et effectuer d'autres configurations dans le fichier _meta.json du répertoire pages. Pour en savoir plus à ce sujet, consultez le Organiser les fichiers section de Documentation de Nextra.

Utiliser des composants React

Les fichiers MDX peuvent inclure JSX, qui est le langage utilisé par React. Vous pouvez créer un composant dans le dossier des composants et l'importer dans n'importe quel document de votre site.

Vous pouvez voir un exemple de la façon dont vous pouvez intégrer des composants dans Markdown dans le un autre.mdx déposer:

## Composant
importer {useState} de 'réagir'
importer des styles depuis '../components/counters.module.css'
export const Compteur = () => { 
 const [count, setCount] = useState (0); 


 retour( 


 A cliqué {count} fois


)
}

<Comptoir />

## Composants externes
importer des compteurs à partir de '../composants/compteurs'

<Compteurs />

Ce fichier Markdown contient une définition pour le composant Counter. Après cela, il importe le composant Counters du Composants annuaire.

Si vous envisagez d'utiliser le même composant sur votre site de documentation, il est préférable de le créer en tant que composant autonome et de l'importer lorsque vous en avez besoin.

En savoir plus sur Markdown

Pour créer du contenu pour votre site de documentation, vous devez savoir utiliser Markdown. La bonne nouvelle est que la syntaxe Markdown est assez facile à comprendre. Lorsque vous combinez vos connaissances de Markdown avec React, vous pouvez créer des sites de documentation vraiment robustes.