Aller au contenu principal
Version: 2.0.0-beta.1 🚧

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 new.docusaurus.io 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@2.0.0-beta.0 @docusaurus/preset-classic@2.0.0-beta.0
astuce

Use new unreleased features of Docusaurus with the @canary npm dist tag

Des problÚmes ?#

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