Comment installer Docusaurus sur linux

Administration système Linux, CMS & Développement Web

Docusaurus est un générateur de site statique moderne optimisé pour créer des sites web de documentation. Il fournit une excellente expérience de documentation prête à l’emploi avec des fonctionnalités comme la recherche, le versionnage, l’i18n, etc. Dans ce tutoriel complet, nous allons passer étape par étape comment installer Docusaurus sur votre système.

Prérequis

Avant d’installer Docusaurus, vous devez avoir installé les logiciels prérequis suivants :

Node.js (>=12.13.0,<13.0.0 || >=14.15.0)
Yarn ou NPM

Node.js

Docusaurus est construit avec React et nécessite Node.js pour fonctionner.

$ node -v

Cela imprimera la version installée de Node. Si elle est inférieure à 12.13.0 ou entre 13.0.0 et 14.15.0, vous devez mettre à niveau Node.js sur votre système.

Pour installer Node.js, accédez au site web officiel de Node.js et téléchargez le programme d’installation pour votre système d’exploitation. Suivez les invites pour installer Node.js.

Yarn ou NPM

Docusaurus utilise un gestionnaire de paquets comme Yarn ou NPM pour gérer ses dépendances. Vous devez avoir Yarn ou NPM installé.

Pour vérifier si vous avez Yarn installé :

$ yarn --version

Si Yarn n’est pas installé, vous pouvez l’installer via npm :

$ npm install --global yarn

Pour vérifier si vous avez NPM installé :

$ npm --version

NPM est généralement fourni avec l’installation de Node.js. Si vous ne l’avez pas, vous pouvez installer NPM à partir du site web officiel.

Une fois que vous avez vérifié les prérequis, nous pouvons passer à l’installation de Docusaurus.

Installation de Docusaurus

Il existe deux façons principales d’installer Docusaurus – en utilisant le modèle classique ou en utilisant une seule commande. Nous couvrirons les deux méthodes dans cette section.

1. Utilisation du modèle classique

Le modèle classique fournit un squelette de projet pour vous permettre de démarrer rapidement avec un exemple de contenu. C’est l’approche recommandée si vous débutez avec Docusaurus.

Pour installer Docusaurus à l’aide du modèle classique :

Créez un nouveau répertoire pour votre site Docusaurus :

$ mkdir mon-site-web
$ cd mon-site-web

Exécutez le script d’installation Docusaurus avec npx :

$ npx @docusaurus/init@latest init --template classic

Cela installera toutes les dépendances et créera une structure de projet initiale avec de la documentation exemple, un blog et des pages personnalisées.

Démarrez le serveur de développement Docusaurus :

$ cd mon-site-web
$ npm start

Le site web s’ouvrira sur http://localhost:3000/ où vous pourrez commencer à ajouter du contenu.

C’est tout ! Docusaurus est maintenant installé et exécuté à l’aide du modèle classique.

2. Utilisation d’une seule commande

Vous pouvez également échafauder un site Docusaurus nu en utilisant une seule commande npx :

$ npx @docusaurus/init@latest init

Cela installe Docusaurus et crée une structure de projet minimale sans aucune documentation ou contenu d’exemple.

Pour démarrer le serveur de développement :

$ cd mon-site-web  
$ npm start

Cette approche vous donne une page blanche pour construire votre site de documentation comme vous le souhaitez. Mais vous devrez ajouter la documentation, le blog, les pages personnalisées, etc. vous-même.

Structure du projet

Une fois Docusaurus installé, vous verrez une structure de dossiers générée comme celle-ci :

mon-site-web
├── blog
├── docs
├── src
│   ├── css
│   └── pages
├── static  
├── package.json
├── sidebars.js
├── docusaurus.config.js
└── .gitignore

Voici à quoi servent chacun de ces dossiers et fichiers :

/blog – Contient les articles de blog qui apparaîtront dans la section blog.
/docs – Contient les fichiers Markdown pour la documentation qui apparaîtra dans la section docs.
/src – Contient les composants React, les fichiers CSS, les pages statiques et autre code source.
/src/css – Fichiers CSS pour le style du site.
/src/pages – Pages statiques comme la page d’accueil, à propos, contact, etc.
/static – Les assets statiques comme images, pdfs, etc. vont ici.
package.json – Les dépendances NPM et les scripts pour le développement.
sidebars.js – Configuration pour la navigation latérale gauche.
docusaurus.config.js – Fichier de configuration principal du site.
.gitignore – Indique à git quels fichiers ne pas suivre.

Lancer le serveur de développement

Pour prévisualiser votre site localement, vous pouvez exécuter le serveur de développement Docusaurus :

$ npm start

Cela démarrera le serveur de développement sur http://localhost:3000/ et reconstruira le site web au fur et à mesure que vous apportez des modifications.

La fonctionnalité de rechargement à chaud actualisera automatiquement la page lorsque vous modifiez les fichiers.

Configuration de Docusaurus

Le fichier de configuration principal est docusaurus.config.js situé à la racine.

Ce fichier contient les paramètres pour :

Les métadonnées du site comme le titre, slogan, url, favicon, etc.
Les liens de navigation d’en-tête et de pied de page.
Le thème de couleurs.
CSS et JavaScript personnalisés
Plugins Markdown personnalisés
Ajout de pages personnalisées
Enregistrement de la documentation, du blog, des pages personnalisées
Et bien d’autres options de configuration.

Par exemple, pour changer le titre du site :

// docusaurus.config.js
module.exports = {
  title: 'Mon titre de site', 
  tagline: 'Le slogan de mon site',
  // ...
}

Reportez-vous à la documentation de configuration de Docusaurus pour la liste complète des options.

Le fichier sidebars.js est utilisé pour configurer la navigation latérale gauche de la documentation. Il vous permet de spécifier quels documents doivent être inclus dans la barre latérale et dans quel ordre.

Par exemple :

// sidebars.js
module.exports = {
  tutorialSidebar: [
    'intro',
    'install',
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guide1',
        'guide2'
      ]
    }
  ], 
}

Cela mappe le document intro.md à l’élément de barre latérale “Introduction”, install.md à “Installation” et ainsi de suite.

La documentation Docusaurus fournit une référence complète pour toutes les options de configuration.

Création de pages

Pour ajouter une nouvelle page comme “À propos de nous”, créez un fichier JSX dans src/pages/about.js :

// src/pages/about.js
import React from 'react';
function About() {
  return (
    <main>
      <h1>À propos de nous</h1>
      <p>Cette page vous en dit plus sur nous...</p>
    </main>
  )
}
export default About;

Ce composant React sera rendu en tant que page à l’URL /about.

De même, vous pouvez ajouter des pages comme /contact, /pricing, /terms etc.

Reportez-vous à la documentation Docusaurus sur les pages pour plus de détails.

Ajout d’articles de blog

Pour créer un nouvel article de blog, ajoutez un fichier Markdown dans le répertoire blog. Par exemple :

blog/welcome.md :

---
slug: welcome
title: Bienvenue sur mon blog  
author: Jean Dupont
author_title: Auteur principal  
author_url: https://github.com/jeandupont
author_image_url: https://avatars3.githubusercontent.com/u/123?s=400&v=4
tags: [bonjour, docusaurus]
---
Bienvenue sur mon nouveau blog ! Ceci est mon premier article.
Je vais écrire sur mon parcours avec Docusaurus et partager mes réflexions. Restez pour plus à venir !

Les attributs de l’article vous permettent de personnaliser l’en-tête du blog. Docusaurus lira ces fichiers Markdown et générera une jolie page de blog pour chaque article.

Reportez-vous à la documentation du blog Docusaurus pour plus de détails sur la création d’articles de blog.

Ajout de documentation

Pour ajouter des pages de documentation, créez des fichiers Markdown dans le dossier /docs.

Par exemple :

docs/intro.md

# Introduction
Bienvenue sur mon site de documentation !
Je vais couvrir comment installer Docusaurus et discuter des concepts clés.

docs/install.md

# Installation
Vous pouvez installer Docusaurus en utilisant:
```bash
npm init docusaurus@latest
```
Cela vous permettra de démarrer rapidement.

Les fichiers Markdown seront convertis en HTML et affichés joliment avec des fonctionnalités comme une barre latérale, une navigation, une recherche, etc.

Vous pouvez utiliser des titres, des images, des liens, des blocs de code, la coloration syntaxique et le formatage Markdown.

Reportez-vous à la documentation des fonctionnalités Markdown de Docusaurus pour plus de détails sur les fonctionnalités Markdown disponibles.

Versionnage

Docusaurus facilite le maintien de versions de documentation avec la fonctionnalité de versionnage.

Pour utiliser le versionnage, initialisez d’abord la documentation :

$ npm run docusaurus docs:version 1.0.0

Cela créera un dossier versioned_docs et copiera le contenu de votre dossier docs existant dans le sous-dossier versions/1.0.0.

Vous pouvez ensuite apporter des modifications à la documentation dans le dossier docs qui seront reflétées dans la version latest.

Pour créer une nouvelle version :

$ npm run docusaurus docs:version 1.0.1

Cela copiera le dossier docs actuel dans versions/1.0.1 comme instantané. Vous pouvez basculer entre les versions en les sélectionnant dans le menu déroulant de version.

Reportez-vous au guide de versionnage de Docusaurus pour plus de détails.

Thèmes

Docusaurus est livré avec plusieurs thèmes dont :

Classique – Le thème classique Docusaurus.
Bootstrap – Un thème avec des styles Bootstrap.
Minimal – Un thème minimal avec du CSS brut.

Le thème peut être configuré dans docusaurus.config.js :

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Titre du site',
      logo: {
        alt: 'Logo du site', 
        src: 'img/logo.svg',
      }
    },
  },
  themes: ['@docusaurus/theme-classic'], 
}

Vous pouvez également créer des thèmes personnalisés pour créer votre propre marque.

Reportez-vous à la documentation sur les thèmes pour plus de détails sur la personnalisation des composants comme les barres de navigation, pieds de page, palette de couleurs, etc.

Déploiement

Une fois que votre site Docusaurus est prêt, vous pouvez le déployer facilement.

Tout d’abord, générez les pages HTML statiques :

$ npm run build

Cela générera un dossier build contenant les pages HTML, les bundles JavaScript et les assets.

Vous pouvez maintenant déployer le dossier build sur n’importe quel fournisseur d’hébergement statique comme GitHub Pages, Vercel, Netlify, Azure Static Web Apps, etc.

Par exemple, pour déployer sur GitHub Pages :

Validez le dossier build dans une branche gh-pages sur GitHub.
Définissez le site GitHub Pages pour pointer vers la branche gh-pages.

Reportez-vous aux docs de déploiement de Docusaurus pour obtenir des guides sur le déploiement sur diverses plateformes.

Et c’est tout ! Votre site Docusaurus devrait maintenant être publié en ligne.

Résumé

Dans ce tutoriel, nous avons vu comment :

Installer Docusaurus en utilisant le modèle classique ou la commande unique
Structurer les fichiers et dossiers du projet
Configurer Docusaurus avec docusaurus.config.js
Exécuter le serveur de développement
Créer des pages React
Ajouter des articles de blog
Organiser la documentation avec Markdown
Versionner la documentation
Thème du site Docusaurus
Déployer Docusaurus en production

Docusaurus est un excellent outil pour créer des sites web de documentation avec React. Il fournit une belle expérience prête à l’emploi tout en donnant la flexibilité pour personnaliser et étendre n’importe quoi. J’espère que ce tutoriel vous a aidé à apprendre à vous lancer avec Docusaurus pour votre site de documentation.