Docusaurus : Créer un site avec Docusaurus – Guide complet

À côté des nombreux systèmes de gestion de contenus (CMS) actuellement à succès, tels que WordPress, PrestaShop et bien d’autres… se trouvent des générateurs de sites web statiques. De nos jours, les sites web statiques sont peut-être les moins populaires du web, mais ils existent et servent toujours pour des projets spécifiques. Ils ont, par ailleurs, l’avantage d’être sécurisés, faciles à coder et dotés d’une vitesse de chargement rapide et donc plus de performances.🚀

Si vous envisagez de créer votre propre site web statique, alors vous aurez besoin d’un générateur de sites statiques et Docusaurus en est un. Il est sans doute le plus récent, mais probablement le mieux conçu pour créer des sites en peu de temps.🤗

Objectif

Étape par étape, nous allons nous plonger dans les détails sur le générateur de sites statiques Docusaurus. L’objectif est qu’en lisant cet article jusqu’à la fin, que vous soyez en mesure de déployer votre premier site statique en utilisant cette plateforme. Le processus est quelque peu technique, mais nous sommes ici pour vous l’éclairer.💡

Qu’est-ce que Docusaurus ?

Docusaurus est une plateforme de création de sites web statiques utilisant des packages npm. Cela veut dire que vous pouvez profiter de toute la puissante l’environnement JavaScript Node.js pour générer des sites interactifs au design soigné. Cela, en sachant que npm est entièrement écrit en JavaScript.

Le générateur Docusaurus utilise la bibliothèque React, qui est le plus populaire dans JavaScript. Ainsi, il vous fournit des composants réutilisables pour construire chaque section de votre site, tel que l’en-tête, le pied de page, la barre latérale ou encore la section principale de contenus.

Gardez à l’esprit que Docusaurus est un générateur de sites statiques en pleine croissance. Lancé pour la première fois en 2017 par Facebook, Docusaurus est à sa deuxième version et son environnement de développement web est de plus en plus rendu confortable pour les développeurs. En effet, l’équipe centrale de Docusaurus déploie constamment des nouveautés pour rendre la construction de sites statiques un processus ultrarapide.

Si vous avez déjà un projet créé avec la première version, vous pouvez trouver une documentation sur le site officiel qui vous explique comme migrer vers la deuxième version.

Besoin d'un serveur privé virtuel VPS sécurisé ?

LWS vous conseille sa formule d’hébergement sur VPS en promotion à -75% (offre à partir de 4,99€ par mois au lieu de 19,99 €). Non seulement les performances sont au rendez-vous mais vous profitez en plus d’un support exceptionnel.

Découvrir l'offre

Docusaurus : pour quel type de sites web statiques ?

Docusaurus est présenté comme la meilleure plateforme pour propulser des sites web de documentation en ligne. Mais de plus près, il s’avère bien plus puissant !

Par exemple, avec sa deuxième version publiée il y a plusieurs mois, les développeurs bénéficient d’un environnement convivial avec des fonctionnalités avancées pour concevoir des divers projets en ligne. Vous pouvez notamment l’utiliser pour des :

• Sites web personnel : Docusaurus est probablement l’outil idéal pour présenter votre projet personnel en ligne.
• Pages de produit : vous pouvez utiliser la puissance de React pour propulser des interfaces interactives sur vos pages de produits et inciter davantage vos clients à s’engager.
• Landing pages : vous pouvez également publier des pages de destination statiques en utilisant ce générateur.
• Blog : la version de base de Docusaurus s’installe avec un blog par défaut. Cela veut dire que vous pouvez toujours gérer votre site d’entreprise en dehors du blog qui peut servir à publier des nouvelles sur vos produits ou vos services, etc.

À l’heure actuelle, Docusaurus est déjà utilisé par des nombreuses marques en ligne. Ainsi, des sites tels que React Native, QuestDB, Piano Analytics, Algolia DocSearch sont entièrement conçus avec ce générateur. Et cette communauté d’utilisateurs est toujours en constante évolution.

Comment créer un site avec Docusaurus ?

À présent, vous en savez un peu plus sur ce générateur de sites statiques. Nous allons donc passer à la partie plus pratique qui concerne l’installation ainsi que la création de votre site en utilisant Docusaurus.

Mais avant de commencer, vous devez vous assurer que vous remplissez toutes les conditions nécessaires :

• Disposer de Node.js à sa version 16.14 ou supérieure. Celui-ci fournit une interface de ligne de commandes et une instance de base de données contenant des paquets nécessaires à la configuration du site. Et cela élimine la nécessité d’avoir une base de données supplémentaire pour vos fichiers.
• Vous pouvez installer Node.js sur Windows, macOS ou sur les systèmes Linux. Si vous disposez déjà de l’environnement Node.js, assurez-vous que vous utilisez la version recommandée. Vous pouvez vérifier votre version courante avec la commande node -v. Notez également que Node.js doit être installé avec toutes les dépendances.

Une fois que vous avez rempli tous les prérequis, commencez la phase pratique ci-dessous :

Installer Docusaurus

Rendez-vous dans votre interface de ligne de commande et exécutez la commande ci-dessous :

npx create-docusaurus@latest my-website classic

L’équipe Docusaurus recommande d’utiliser le thème classic pour créer rapidement le squelette de votre site. Mais vous pouvez toujours changer cela plus tard lorsque vous maîtrisez déjà cet environnement de développement web.

La commande exécutée ci-dessus va créer un certain nombre d’éléments dans un nouveau dossier pour votre site. Elle ajoute notamment :

• Une section de documentation
• Un blog
• Des pages personnalisées
• Un framework CSS pour vous permettre de gérer plus tard du style

En dehors du modèle classic, vous pouvez utiliser sa variante --typescript comme une alternative. Dans ce cas, la commande à exécuter ajoute le drapeau nécessaire et prend la syntaxe ci-dessous :

npx create-docusaurus@latest my-website classic --typescript

Docusaurus vous permet par ailleurs de prévisualiser toutes les dernières modifications effectuées sur votre site en utilisant un serveur local. Pour cela, vous devez exécuter la commande ci-dessous :

cd my-website
npm run start

Celle-ci ouvre automatiquement une fenêtre de navigateur à l’adresse http://localhost:3000.

De plus, vous avez aussi la possibilité de créer un site entièrement personnalisé que vous pouvez ensuite déployer sur un espace d’hébergement des sites statiques. Dans ce dernier cas, vous devez exécuter la commande ci-après :

npm run build

Une fois que vous aurez terminé, vous pouvez ensuite copier les fichiers de votre site dans le répertoire /build pour faire le déploiement.

Gérer la structure de votre site

Après l’installation de Docusaurus sur votre environnement de développement web, vous pouvez prévisualiser l’architecture de base de votre site. Si vous avez choisi le thème classic , le squelette par défaut ressemble à ceci :

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

C’est le modèle de base de fichiers de votre site Docusaurus. Mais vous pouvez toujours le modifier en une architecture personnalisée. Nous y reviendrons juste après.

Pour l’instant, voyons quelques détails à connaître sur ces fichiers fondamentaux :

• /blog/ : contient les fichiers Markdown de votre section de blog. Et Markdown est le langage de balisage utilisé sur Docusaurus. Vous pouvez modifier le nom du blog en définissant une option path.
• /docs/ : il contient tous les fichiers relatifs aux documents de votre site. Utilisez le fichier sidebars.js pour modifier l’ordre de la barre latérale.
• /src/ : déploie des fichiers essentiellement non-documentaires. Ce sont notamment des pages ou des composants personnalisés React.
• /src/pages : convertit tous les fichiers JSX/TSX/MDX en des pages pour votre site.
• /static/ : c’est le répertoire statique qui contient tout le contenu qui sera copié dans le répertoire de construction final.
• /docusaurus.config.js : c’est le fichier contenant toutes les instructions pour la configuration de votre site. Il remplace le fichier siteConfig.js dans la version 1 (v1) de Docusaurus.
• /package.json : c’est le fichier qui contient tous les paquets (dépendances et scripts) de votre site. Il permet en outre d’installer des paquets npm.
• /sidebars.js : gère et spécifie l’ordre de documents dans la barre latérale.

Comment personnaliser votre site Docusaurus ?

Vous avez maintenant un squelette de base pour votre site que vous pouvez personnaliser. Docusaurus hérite d’une architecture assez simple à comprendre et surtout à modifier. Vous pouvez à présent modifier les différentes sections de votre installation afin de les correspondre à vos attentes. Voyons les options dont vous disposez pour publier un site entièrement personnalisé avec Docusaurus.

Pour apporter des modifications à votre installation, vous devez disposer d’un environnement de développement intégré (IDE) ou encore un simple éditeur de texte.

Personnaliser la page d’accueil de votre site

Vous devez toujours commencer par ajuster votre page d’accueil, car c’est celle que les visiteurs doivent visiter en premier. Pour cela, vous devez rechercher le fichier src/pages/index.js et y ajouter votre propre code ou modifier celui qui existe.

Vous ne devez pas l’oublier, Docusaurus utilise la bibliothèque React. Effectuez vos modifications à l’intérieur du fichier et enregistrez-le une fois que vous avez terminé.

Modifier la configuration du site

Pour vous faciliter la tâche, Docusaurus fournit une architecture de base pour que vous ne puissiez pas écrire votre code à partir de rien. Ainsi, dans le fichier de configuration docusaurus.config.js, vous pouvez personnaliser différentes sections de votre installation.

Personnaliser le nom et la description du site

Naviguez jusqu’à trouver les lignes de codes ci-dessous dans votre fichier de configuration. Vous pouvez ensuite modifier le nom du site et adjoindre une description comme bon vous semble.

const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',

Développer la barre de navigation

Pour personnaliser le code de la barre de navigation, vous devez trouver l’élément navbar. Cette barre peut intégrer des liens internes ou externes à votre site.

Ensuite, vous pouvez ajouter des nouveaux éléments à votre barre en utilisant l’élément themeConfig.navbar.items. Ainsi, votre code peut ressembler à ceci :

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          type: 'docsVersionDropdown',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/facebook/docusaurus',
          position: 'right',
          className: 'header-github-link',
          'aria-label': 'GitHub repository',
        },
      ],
    },
  },
};

N’oubliez pas de personnaliser le code pour ajouter des détails propres à votre site.

Ajouter une barre de recherche à la barre de navigation

La barre de recherche peut-être affichée dans une position au choix sur votre barre de navigation. Vous devez vous servir de la configuration ci-dessous :

module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

Le code affiche votre barre de recherche à droite. Mais vous pouvez toujours modifier la valeur de position en left pour par exemple, l’afficher à Gauche.

Masquer la barre de navigation

Vous avez également la possibilité de masquer la barre de navigation lorsque les visiteurs défilent la page vers le bas et la réafficher lors du défilement vers le haut. Servez-vous pour cela du code suivant :

module.exports = {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

Personnaliser le contenu de pied de page du site

Vous devez utiliser le fichier themeConfig.footer. Dans cette section, vous pouvez ajouter ou retirer n’importe quel élément. Par exemple, vous pouvez y ajouter un logo et un avis de copyright avec la configuration suivante :

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'LWS Logo',
        src: 'img/lws_logo.png',
        href: 'https://lws.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} LWS, Inc. Built with Docusaurus.`,
    },
  },
};

N’oubliez pas d’ajuster les détails (largeur, hauteur et lien du logo ou encore le nom de votre projet…) afin qu’ils correspondent à votre entreprise. Notez que vous pouvez également ajouter du HTML personnalisé dans votre pied de page.

Ajouter ou modifier les liens de pied de page

Vous pouvez modifier les liens de pied de pages en utilisant le fichier themeConfig.footer.links. Là, vous avez deux possibilités : ajouter un pied de page simple (avec une seule colonne) ou celui adoptant une approche multi-colonnes.

Par exemple, voici à quoi peut ressembler la configuration d’un pied de pages multi-colonnes :

module.exports = {
  footer: {
    links: [
      {
        title: 'Informations',
        items: [
          {
            label: 'Informations',
            to: 'docs/',
          },
          {
            label: 'LWS about',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Ressources',
        items: [
          {
            label: 'Tutoriels lws',
            href: 'https://lws.com/tutoriels',
          },
          {
            label: 'Hebergement',
            href: 'https://lws/hebergement',
          },
          {
            label: 'Twitter',
            href: 'https://twitter.com/lws',
          },
          {
            html: `
                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

Vous ne devez pas toujours oublier de personnaliser les différents détails afin qu’ils correspondent à vos critères.

Conclusion

🥳Toutes nos félicitations pour avoir lu cet article. Vous voilà à présent, suffisamment prêt, à construire votre premier site en utilisant Docusaurus. Ce didacticiel s’est avéré un véritable guide, celui qui va vous conduire pendant vos premiers pas avec ce générateur de sites web statiques. Ainsi, vous savez ce qu’il vous reste à faire !

De plus en plus de développeurs utilisent Docusaurus pour créer des sites ou des applications rapides, sécurisés et faciles à maintenir. N’hésitez pas à l’essayper !

Si vous avez des questions ou des ajouts sur la façon d’utiliser Docusaurus pour créer un site, écrivez-nous en utilisant la section Commentaires.