Aller au contenu principal
Version: 2.0.0-beta.3

Installation

Docusaurus est essentiellement un ensemble de paquets de npm .

astuce

Utilisez la Procédure accélérée pour comprendre Docusaurus en 5 minutes ⏱ !

Utilisez docusaurus.new pour tester immédiatement Docusaurus dans votre navigateur !

Pré-requis#

  • Node.js version >= 12.13.0 ou supérieure (qui peut être vérifiée en exécutant node -v). Vous pouvez utiliser nvm pour gérer plusieurs versions de Node sur une seule machine installée
  • Yarn version >= 1.5 (qui peut être vérifié en exécutant yarn --version). Yarn est un gestionnaire de paquets performant pour JavaScript et remplace le client npm. Il n'est pas strictement nécessaire, mais fortement encouragé.

Structurer un site web d'un projet#

La façon la plus simple d'installer Docusaurus est d'utiliser l'outil en ligne de commande qui vous aide à créer un squelette de site web Docusaurus. Vous pouvez exécuter cette commande n'importe où dans un nouveau dépôt vide ou dans un dépôt existant, elle créera un nouveau répertoire contenant les fichiers de structure.

npx @docusaurus/init@latest init [name] [template]

Exemple :

npx @docusaurus/init@latest init my-website classic

Si vous ne spécifiez pas le name ou template, il vous demandera de le faire. Nous recommandons le template classic pour que vous puissiez commencer rapidement et il contient des fonctionnalités disponibles dans Docusaurus 1. Le template classic contient @docusaurus/preset-classic qui inclut une documentation standard, un blog, des pages personnalisées et un framework CSS (avec support du mode sombre). Vous pouvez être opérationnel très rapidement avec le template classic et personnaliser les choses plus tard, lorsque vous serez plus familier avec Docusaurus.

[FB-Only]: Si vous configurez un nouveau site web Docusaurus pour un projet open source Facebook, utilisez le template facebook à la place, qui est fourni avec quelques valeurs par défaut utiles propres à Facebook:

npx @docusaurus/init@latest init my-website facebook

[Experimental]: Si vous voulez configurer un nouveau site web en utilisant bootstrap, utiliser le template bootstrap , comme ceci :

npx @docusaurus/init@latest init my-website bootstrap

Si vous voulez ignorer l'installation des dépendances, utilisez l'option --skip-install , comme ceci :

npx @docusaurus/init@latest init my-website classic --skip-install

Structure du projet#

En supposant que vous avez choisi le template classic et nommé votre site my-website, vous verrez les fichiers suivants générés dans un nouveau répertoire my-website/ :

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

Récapitulatif de la structure du projet#

  • /blog/ - Contient les fichiers Markdown du blog. Vous pouvez supprimer le répertoire si vous ne voulez pas ou n'avez pas besoin d'un blog. Vous trouverez plus de détails dans le guide du blog
  • /docs/ - Contient les fichiers Markdown pour la documentation. Personnalisez l'ordre de la barre latérale des docs dans sidebars.js. Vous trouverez plus de détails dans le guide des docs
  • /src/ - Fichiers de non-documentation comme les pages ou les composants React personnalisés. Vous n'êtes pas obligé de placer vos fichiers de non-documentation ici, mais les placer dans un répertoire centralisé permet de les spécifier plus facilement au cas où vous auriez besoin de faire une sorte de vérification/traitement
    • /src/pages - Tous les fichiers de ce répertoire seront convertis en page de site. Vous trouverez plus de détails dans le guide des pages
  • /static/ - Répertoire statique. Tout contenu à l'intérieur sera copié à la racine du répertoire final de build
  • /docusaurus.config.js - Un fichier de configuration contenant la configuration du site. Ceci est l'équivalent de siteConfig.js dans Docusaurus v1
  • /package.json - Un site Web Docusaurus est une application React. Vous pouvez y installer et utiliser tous les paquets npm que vous souhaitez
  • /sidebar.js - Utilisé par la documentation pour spécifier l'ordre des documents dans la barre latérale

Exécution du serveur de développement#

Pour prévisualiser vos modifications au fur et à mesure que vous modifiez les fichiers, vous pouvez lancer un serveur de développement local qui servira votre site Web et reflétera les dernières modifications.

cd my-websitenpm run start

Par défaut, une fenêtre du navigateur s'ouvre depuis l'adresse http://localhost:3000.

Félicitations ! Vous venez de créer votre premier site Docusaurus ! Naviguez sur le site pour voir ce qui est disponible.

Construction#

Docusaurus est un générateur de site web statique moderne donc nous avons besoin de construire le site web dans un répertoire de contenu statique et de le mettre sur un serveur web pour qu'il puisse être consulté. Pour construire le site web :

npm run build

Et le contenu sera généré dans le répertoire /build , qui peut être copié dans n'importe quel service d'hébergement de fichiers statique comme GitHub pages, Vercel ou Netlify. Consultez la documentation sur le déploiement pour plus de détails.

Mise à jour de votre version de Docusaurus#

Il y a de nombreuses façons de mettre à jour votre version de Docusaurus. Une façon garantie est de changer manuellement le numéro de version dans package.json à la version désirée. Notez que tous les paquets nommés @docusaurus/ doivent utiliser la même version.

important

Veuillez mettre à jour la dernière version de Docusaurus 2 indiquée en haut de la page, et non celle indiquée ci-dessous.

package.json
"dependencies": {  "@docusaurus/core": "^2.0.0-beta.0",  "@docusaurus/preset-classic": "^2.0.0-beta.0",  // ...}

Ensuite, dans le répertoire contenant le fichier package.json, exécutez la commande d'installation de votre gestionnaire de paquets :

npm install

Pour vérifier que la mise à jour a été effectuée avec succès, exécutez :

npx docusaurus --version

Vous devriez voir la version correcte en résultat.

Alternativement, si vous utilisez Yarn, vous pouvez faire :

yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest
astuce

Utilisez de nouvelles fonctionnalités inédites de Docusaurus avec la balise @canary npm dist tag

Des problèmes ?#

Demandez de l'aide sur Stack Overflow, sur notre dépôt GitHub ou Twitter.