Si vous êtes familier avec Next.js, vous pouvez l’utiliser pour développer facilement un site de documentation. Le framework Nextra s’occupe des détails pour vous ; tout ce que vous avez à faire est d’ajouter du contenu Markdown ou HTML et des données YAML ou JSON.
Suivez ces étapes pour construire un site de documentation en utilisant 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 nouvelles docs et pages, à écrire du Markdown et à inclure des composants React.
Exigences pour construire un site de documentation avec Nextra
Commencez par installer Node.js si vous ne l’avez pas encore fait. La dernière version de Node.js est livrée avec npm, le gestionnaire de paquets de node, dont vous aurez besoin pour installer les dépendances pour ce projet.
En plus de Node.js, vous devrez installer Git. Vous avez besoin de Git pour déployer le site sur des pages GitHub, Netlify ou un autre hébergeur. Vous aurez également besoin d’un éditeur de code avancé, tel que VS Code.
Installation de Nextra
Vous pouvez utiliser un modèle nextra docs pour démarrer un site de documentation. Lancez une invite de commande et naviguez jusqu’au répertoire dans lequel vous souhaitez configurer votre projet. Exécutez ensuite la commande suivante pour démarrer le site de documentation :
git clone https://github.com/shuding/nextra-docs-template
Cette commande va scaffold une application dans le répertoire courant. Ensuite, exécutez la commande suivante pour installer les dépendances :
cd nextra-docs-template
npm install
Une fois l’installation terminée, démarrez l’application. Pour ce faire, exécutez la commande suivante dans votre terminal :
npm run dev
Cette commande démarre un serveur de développement sur localhost:3000. Suivez le lien sur votre terminal pour afficher 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 Autre page. En dessous de ces liens, vous trouverez une page nommée Satori, imbriquée à l’intérieur de la page Avancé (Dossier A) . Enfin, dans la zone de navigation, vous trouverez des liens vers les pages suivantes À propos de et Contact pages.
Pour comprendre le fonctionnement de ces pages, il faut d’abord comprendre comment Next.js rend les pages.
Comprendre la structure des répertoires
Puisque Nextra utilise le framework Next.js, il rend chaque fichier dans le répertoire pages/ en tant que page séparée.
A l’intérieur de la pages vous trouverez quatre fichiers modèles : about.mdx, avancé.mdx, autre.mdx, et index.mdx. Chacun de ces fichiers correspond à une page du site web ; par exemple, index.mdx correspond à la page d’accueil. L’URL localhost:3000/about correspond à about.mdxet ainsi de suite.
Intérieur pagesil y a aussi un dossier nommé avancé, hébergeant un seul fichier nommé satori.mdx. L’URL de ce fichier sera localhost:3000/advanced/satori.
Remarquez que chacun de ces fichiers se termine par un .mdx extension.
Qu’est-ce que MDX ?
Si vous avez de l’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 rend JSX dans un document Markdown. Grâce à MDX, vous pouvez écrire des composants React et les importer dans vos documents Markdown lorsque cela est nécessaire. Les fichiers MDX se terminent par l’extension .mdx et peuvent inclure à la fois du Markdown et du JSX.
MDX vous permet de combiner vos connaissances en Markdown avec React pour créer des composants réutilisables. Vous pouvez créer des modules CSS pour styliser les composants. Cela vous aide à organiser vos composants pour améliorer la lisibilité et la maintenabilité.
Comment éditer des pages existantes dans le site de documentation
Pour éditer une page existante, il suffit d’ouvrir le fichier correspondant et d’y apporter des modifications. Les langages supportés sont Markdown et JSX.
Par exemple, ouvrez le fichier index.mdx et remplacez le contenu par ceci :
# Welcome To My Documentation
I'm happy to see you here. Thanks
## My Socials
Follow me on [Twitter](https://twitter.com/kingchuuks) and [LinkedIn](https://linkedin.com/in/kingchuks)
Cet exemple utilise Markdown pour formater le contenu. Il contient un titre de niveau 1, un titre de niveau 2 et deux liens vers des 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 page, vous trouverez également la date de 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 la section pages/ ou à l’intérieur d’un dossier. 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. Ouvrez un fichier nommé installation.mdx dans votre éditeur de code et collez-y le code Markdown suivant :
# Installation Guide
Follow this guide to install my package in your project
## 1. Install Node.js
To install Node.js, visit the
[Node.js documentation site](https://nodejs.org/en/download)
Enregistrez le fichier et consultez le navigateur. Vous trouverez l’étiquette Installation dans le menu latéral. Lorsque vous cliquez sur le lien, le contenu de la rubrique 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, reportez-vous à la page Organiser les fichiers de la documentation de Nextra.
Utilisation 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 components et l’importer dans n’importe quel document de votre site.
Vous pouvez voir un exemple de la façon dont vous pouvez incorporer des composants dans Markdown dans le fichier autre.mdx fichier :
## Component
import {useState} from 'react'
import styles from '../components/counters.module.css'
export const Counter = () => {
const [count, setCount] = useState(0);
return(
<div>
<button onClick={() => setCount(count+1)} className={styles.counter}>
Clicked {count} times
</button>
</div>
)
}
<Counter />
## External Components
import Counters from '../components/counters'
<Counters />
Ce fichier Markdown contient une définition du composant Counter. Ensuite, il importe le composant Compteurs de la base de données composants répertoire.
Si vous avez l’intention d’utiliser le même composant sur l’ensemble de 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 comment utiliser Markdown. La bonne nouvelle, c’est que la syntaxe Markdown est assez facile à assimiler. Lorsque vous combinez votre connaissance de Markdown avec React, vous pouvez créer des sites de documentation vraiment robustes.