Pour les sites web légers, les applications et autres petits projets, de plus en plus de développeurs se tournent vers les générateurs de sites statiques plutôt que vers WordPress ou d’autres systèmes de gestion de contenu (CMS). Les sites statiques offrent un moyen simple et efficace de créer des sites web et des applications qui sont rapides, sécurisés et faciles à maintenir.
Docusaurus est l’un de ces générateurs de sites statiques – et il gagne rapidement en popularité dans la communauté des développeurs.
Dans ce billet, nous allons plonger dans les avantages de l’utilisation de Docusaurs comme générateur de sites statiques et expliquer pourquoi il est de plus en plus apprécié par les développeurs.
Qu’est-ce que Docusaurus ?
Docusaurus est un générateur de sites statiques populaire qui utilise React, l’une des principales bibliothèques JavaScript, comme bibliothèque d’interface utilisateur pour la création de pages. Comme d’autres générateurs de ce type, il est facile à configurer et à modifier et, surtout, il vous fournit tout ce dont vous avez besoin pour lancer votre site web statique.
Ce qui distingue Docusaurus, cependant, c’est qu’il vous aide à créer et à gérer un site web où le le contenu joue un rôle clé. Il vous permet de construire rapidement et facilement un site web complet – avec une fonction de blog – qui met en valeur votre contenu dès le départ.
Comme le contenu est au centre des préoccupations avec Docusaurus, il est parfait pour créer des sites de documentation comme les wikis. Il utilise également markdown, qui est idéal à la fois pour la collaboration et le stockage dans un dépôt git. De plus, il dispose d’une tonne de fonctionnalités étonnantes comme l’i18n, la recherche et les thèmes personnalisés, dont nous parlerons plus en détail plus tard.
Voici quelques-unes des caractéristiques qui font de Docusaurus une option solide :
- Construit avec React
- Prise en charge de MDX v1
- Prise en charge de l’intégration de composants React via Markdown
- Versionnage des documents
- Compatibilité avec Git, Crowdin et d’autres gestionnaires de traduction pour la traduction de documents et le déploiement en masse ou individuel
Qui utilise Docusaurus ?
Docusaurus a été créé par Facebook, il n’est donc pas surprenant qu’il soit actuellement utilisé par de nombreuses grandes marques et entreprises sur le web.
Voici quelques-unes des plus grandes marques qui utilisent Docusaurus aujourd’hui (d’autres suivront bientôt, car la popularité de Docusaurus ne cesse de croitre) :
Et d’autres rejoignent leurs rangs chaque jour.
Comment installer Docusaurus
Docusaurus est très simple à installer et ne nécessite que quelques minutes. Dans ce tutoriel, nous allons construire un site de documentation avec un blog, et nous allons personnaliser l’apparence du site.
Et voici la partie la plus cool : Il nous faudra moins d’une heure pour tout mettre en route.
Plongeons-y !
Exigences
Docusarus nécessite Node.js 16.14 ou plus récent. C’est un SSG à fichier plat, ce qui signifie que vous n’aurez pas besoin d’une base de données supplémentaire.
Si vous ne disposez pas déjà de Node.js 16.14+, vous devrez commencer par installer Node.js ou mettre à jour votre version actuelle. Vous pourrez ensuite passer au processus d’installation de Docusaurus ci-dessous.
Nous allons également utiliser l’exemple de site Docusaurus de ce dépôt GitHub. Vous pouvez l’utiliser ou utiliser une installation propre de Docusaurus pour ce tutoriel.
Processus d’installation
Pour commencer le processus d’installation de Docusaurus, vous devez d’abord exécuter la commande suivante :
npx create-docusaurus@latest classicCela créera un dossier pour votre projet et échafaudera le thème classique à l’intérieur de celui-ci. Le thème classique contient déjà certaines fonctionnalités pré-configurées comme un blog, des pages personnalisées et un framework CSS.
Après l’installation, vous devez ensuite exécuter la commande suivante pour démarrer le serveur local :
npm startSi vous souhaitez créer une version optimisée prête à être déployée, vous devez plutôt exécuter cette commande :
npm run buildStructure
Une fois que vous avez installé votre instance de Docusaurus, vous pourrez ouvrir votre répertoire de projet et regarder de plus près le « squelette » de votre nouveau site.
Voici à quoi ressemble la structure des fichiers :
my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.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.lockIl y a quelques détails à noter concernant quelques-uns de ces fichiers et dossiers :
/blog: Contient tous les fichiers liés à votre blog./docs: Contient tous les fichiers liés à vos docs. Vous pouvez personnaliser leur ordre dans le fichier sidebar.js./src: Contient tous les fichiers non-documentaires comme les pages ou les composants personnalisés./src/pages: Tous les fichiers JSX/TSX/MDX seront transformés en pages./static: Les fichiers statiques qui seront copiés dans le dossier de construction final.docusaurus.config.js: Le fichier de configuration de Docusaurus.packaged.json: Chaque site Docusaurus est une application React, donc vous trouverez ici toutes les dépendances et les scripts qu’il utilise pour React.sidebar.js: Ici, vous pouvez spécifier l’ordre des documents dans la barre latérale.
Personnalisation de votre installation Docusaurus
Comme vous pouvez le constater par la simplicité de sa structure de fichiers, Docusaurus est facile à utiliser et à naviguer. De même, la personnalisation de votre site Docusaurus est un jeu d’enfant. Vous pouvez ouvrir et modifier ces fichiers à l’aide de votre éditeur de texte ou IDE préféré.
Passons en revue quelques-unes des options de personnalisation dont vous disposerez dès la sortie de l’emballage.
Page d’accueil
La première chose qui vous démangera probablement sera de personnaliser la page d’accueil par défaut pour exposer votre propre projet. Heureusement, il n’est pas compliqué d’apporter les modifications que vous souhaitez à la page d’accueil de Docusaurus.
Pour modifier la page d’accueil, ouvrez le fichier src/pages/index.js et effectuez les ajustements directement à l’intérieur. Il s’agit d’une page React typique, vous pouvez donc la modifier ou la reconstruire en changeant le contenu ou en créant des composants React personnalisés.
Fichier de configuration
Ensuite, nous allons nous plonger dans le fichier crucial docusaurus.config.js et modifier certains détails importants pour notre instance.
Nom et description
Dans le fichier de configuration, vous trouverez :
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',Modifiez simplement ces détails pour les adapter aux besoins de votre site, puis enregistrez le fichier.
Barre de navigation
Pour modifier votre barre de navigation, localisez l’élément navbar.
Pour notre exemple ici, nous voulons ajouter un lien vers Kinsta, renommer l’élément « Tutorial » en « Starter documentation », et ajouter le logo Kinsta.
Voici comment nous procèderions :
navbar: {
title: 'Kinsta starters',
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo-alpha-purple.png',
},
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
{to: '/blog', label: 'Blog', position: 'left'},
{
href: 'https://github.com/kinsta',
label: 'GitHub',
position: 'right',
},
],
},Pied de page
La personnalisation du pied de page dans Docusaurus se compose de deux sections : le contenu du pied de page lui-même, et les liens du pied de page.
Contenu du pied de page
L’essentiel du contenu de votre pied de page (hors liste de liens) peut être placé dans votre fichier themeConfig.footer. C’est l’endroit idéal pour ajouter un logo et un avis de copyright.
Voici comment nous avons modifié la configuration de notre pied de page :
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Kinsta Logo',
src: 'img/kinsta-logo.png',
href: 'https://kinsta.com',
width: 160,
height: 51,
},
copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
},
},
};Liens de pied de page
La modification des liens du pied de page est similaire à celle de la barre de navigation supérieure : Trouvez la section footer dans docusaurus.config.js et modifiez-la jusqu’à ce qu’elle corresponde à vos besoins.
Voici à quoi ressemble la section footer que nous avons modifiée :
footer: {
style: 'dark',
links: [
{
title: 'Docs',
items: [
{
label: 'Kinsta starters',
to: '/docs/intro',
},
],
},
{
title: 'Talk with us',
items: [
{
label: 'Discord',
href: 'https://discord.gg/vjRPMhFaBA',
},
{
label: 'Support',
href: 'https://kinsta.com/kinsta-support/',
},
{
label: 'Twitter',
href: 'https://twitter.com/kinsta',
},
],
},
{
title: 'More',
items: [
{
label: 'Application Hosting',
href: 'https://kinsta.com/application-hosting/',
},
{
label: 'Database Hosting',
href: 'https://kinsta.com/database-hosting/',
},
{
label: 'WordPress Hosting',
href: 'https://kinsta.com/wordpress-hosting/',
},
{
label: 'DevKinsta',
href: 'https://kinsta.com/devkinsta/',
},
],
},
],
};Couleurs et CSS
Le préréglage classique de Docusaurus utilise le framework CSS Infima. Dans cette optique, les créateurs de Docusaurus ont créé un outil web très utile pour vous aider à modifier les couleurs et autres éléments et déclarations CSS.
Une fois que vous aurez saisi vos préférences sur la page, l’outil génèrera un fichier .css personnalisé – complet avec une belle suite de tons complémentaires – en quelques secondes. Vous pouvez ensuite copier ce nouveau fichier CSS dans le répertoire /src/css de votre projet à titre de référence.
Documentation
Toute la documentation de votre nouveau site web est stockée dans le dossier /docs. Bien entendu, vous pouvez modifier le nom du dossier dans docusaurus.config.js.
Créez simplement les fichiers markdown dans votre éditeur de texte ou HTML et déposez-les dans ce dossier. Chaque fichier devrait ressembler à ceci :
---
id: the-id
title: Title
---
# Rest of the documentSur la base de l’ID, Docusaurus construit les URL des articles de ce sous-dossier : yourdomain.com/docs/{id}
Nous pouvons également créer des sous-dossiers si nous voulons diviser notre documentation en différentes sections logiques. Cependant, nous devrons effectuer un peu de travail supplémentaire pour que ces sous-répertoires fonctionnent comme nous l’attendons.
Supposons que nous créions un nouveau dossier de documents appelé « Starters » Si nous devions ensuite rafraichir la page d’accueil et cliquer sur le nouveau lien Starters automatiquement ajouté à notre colonne latérale, nous obtiendrions une erreur – car il n’y a pas encore de page d’index dans notre nouveau dossier.
La façon la plus simple de résoudre ce problème est de créer un fichier _category_.json qui générera l’index de toutes les pages stockées dans ce dossier. Il vous suffit d’ajouter le code suivant :
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Kinsta Starters"
},
};Comme vous pouvez le voir, la colonne latérale se régénère pour correspondre à la structure de vos fichiers. C’est parce que le fichier sidebar.js contient ce tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
Si vous préférez vous occuper de cela vous-même, vous pouvez simplement changer ceci en quelque chose comme ceci :
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],Blog
Docusaurus comprend un module de blog très pratique. Disposer d’un blog à côté de votre site web principal peut s’avérer très utile pour informer votre base d’utilisateurs des changements survenus dans votre projet, ou pour conserver des notes sur le projet sous forme de journal des modifications.
Chaque article se compose d’une partie frontmatter, comme ceci :
---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---…et, bien sûr, le contenu lui-même. Il dispose également d’une balise très utile, qui permet de limiter le résumé de l’article affiché sur toutes les listes d’articles.
C’est aussi une bonne idée de créer un fichier authors.yml pour les crédits. Ce fichier ressemble à ceci :
palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.pngGrâce à ce fichier, vous aurez toutes les données de l’auteur en un seul endroit pour une référence facile.
Comment déployer votre site Docusaurus sur Kinsta
En plus des sites WordPress, des applications autonomes et des bases de données, Kinsta peut héberger des sites statiques.
Cela signifie qu’il est parfait pour vos sites Docusaurs – et pour gérer tous vos projets web – directement depuis votre tableau de bord MyKinsta.
Assurez-vous d’abord de pousser votre code vers un fournisseur Git préféré (Bitbucket, GitHub ou GitLab), puis suivez les étapes ci-dessous pour déployer votre site statique sur Kinsta :
-
- Connectez-vous ou créez un compte pour voir votre tableau de bord MyKinsta.
- Autorisez Kinsta avec votre fournisseur Git.
- Cliquez sur Sites statiques dans la colonne latérale de gauche, puis sur Ajouter un site.
- Sélectionnez le dépôt et la branche à partir desquels vous souhaitez effectuer le déploiement.
- Attribuez un nom unique à votre site.
- Ajoutez les réglages de construction dans le format suivant :
- Commande de construction :
npm run build - Version de Node :
18.16.0 - Répertoire de publication :
build
- Commande de construction :
- Enfin, cliquez sur Créer un site.
Si vous êtes arrivé jusqu’ici sans erreur, alors félicitations – vous venez de déployer votre site Docusaurus via Kinsta!
Voici un premier aperçu de notre site d’exemple sur Kinsta :
Comme alternative à l’hébergement de sites statiques, vous pouvez opter pour le déploiement de votre site statique avec l’hébergement d’applications de Kinsta, qui fournit une plus grande flexibilité d’hébergement, un plus large éventail d’avantages et l’accès à des fonctionnalités plus robustes. Par exemple, l’évolutivité, le déploiement personnalisé à l’aide d’un fichier Docker, et des statistiques complètes englobant des données en temps réel et historiques.
Résumé
Avec ses fonctionnalités étonnamment puissantes, son design convivial, sa navigation intuitive et l’accent mis sur le contenu, il n’est pas difficile de comprendre pourquoi Docusaurus est considéré comme un excellent outil pour tout développeur cherchant à déployer et à maintenir facilement un site et/ou un blog de documentation statique rationalisé et bien organisé.
Une fois que vous aurez rempli votre site de contenu que vos visiteurs apprécieront, vous commencerez à prendre note des fonctions intégrées supplémentaires qui s’avèrent pratiques. Par exemple, les capacités d’optimisation des moteurs de recherche de Docusaurus sont parfaites pour vous aider à obtenir une meilleure visibilité auprès d’un public plus large pendant que vous travaillez sur d’autres techniques pour progresser dans les classements SEO.
Avez-vous construit quelque chose avec Docusaurus ? Partagez vos projets et votre expérience avec nous dans la section des commentaires ci-dessous.
Maciek est un développeur web qui travaille chez Kinsta en tant qu'analyste chargé du développement. En dehors des heures de travail, il passe le plus clair de son temps à coder, à essayer de trouver des nouvelles intéressantes pour ses bulletins d'information ou à boire du café.
Laisser un commentaire