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

CLI

Docusaurus met à disposition un ensemble de scripts vous aidant dans la génération, le lancement et le déploiement de votre site web.

Une fois votre site Web démarré, la source du site Web contient les scripts Docusaurus que vous pouvez appeler avec votre gestionnaire de paquets :

package.json
{  // ...  "scripts": {    "docusaurus": "docusaurus",    "start": "docusaurus start",    "build": "docusaurus build",    "swizzle": "docusaurus swizzle",    "deploy": "docusaurus deploy",    "clear": "docusaurus clear",    "serve": "docusaurus serve",    "write-translations": "docusaurus write-translations",    "write-heading-ids": "docusaurus write-heading-ids"  }}

Index#

Commandes CLI Docusaurus#

Voici une liste des commandes CLI de Docusaurus et de leurs utilisations :

docusaurus start [siteDir]#

Construit et sert un aperçu de votre site localement avec Webpack Dev Server.

Options#

NomPar défautDescription
--port3000Spécifie le port du serveur dev.
--hostlocalhostSpécifie un hôte à utiliser. Par exemple, si vous voulez que votre serveur soit accessible à l'extérieur, vous pouvez utiliser --host 0.0.0.0.
--hot-onlyfalseActive le remplacement des modules à chaud sans rafraîchissement de page en cas d'échec de construction. Plus d'informations ici.
--no-openfalseN'ouvre pas automatiquement la page dans le navigateur.
--configundefinedChemin vers le fichier de configuration de docusaurus, par défaut [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]falseUtilisez l'interrogation des fichiers plutôt que la surveillance du rechargement en direct comme solution de rechange dans les environnements où la surveillance ne fonctionne pas. Plus d'informations ici.
important

Veuillez noter que certaines fonctionnalités (par exemple, les liens d'ancrage) ne fonctionneront pas en développement. La fonctionnalité marchera comme prévu en production.

Activation HTTPS#

Il y a plusieurs façons d'obtenir un certificat. Nous utiliserons mkcert comme exemple.

  1. Exécutez mkcert localhost pour générer localhost.pem + localhost-key.pem

  2. Exécutez mkcert -install pour installer le cert dans votre magasin de confiance, et redémarrez votre navigateur

  3. Lancez l'application avec les variables d'environnement HTTPS de Docusaurus :

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
  1. Ouvrez https://localhost:3000/

docusaurus build [siteDir]#

Compile votre site pour la production.

Options#

NomPar défautDescription
--bundle-analyzerfalseAnalyse votre bundle avec l'analyseur de bundle de webpack.
--out-dirbuildLe chemin complet du nouveau répertoire de sortie, relatif à l'espace de travail actuel.
--configundefinedChemin vers le fichier de configuration de docusaurus, par défaut [siteDir]/docusaurus.config.js
--no-minifyfalseConstruit un site web sans minimiser les bundles JS/CSS.
info

Pour une minification avancée du bundle CSS, nous utilisons le preset cssnano avancé (ainsi que plusieurs plugins PostCSS supplémentaires) et l'optimisation de niveau 2 de clean-css. Si, à la suite de cette minification CSS avancée, vous trouvez des CSS cassés, construisez votre site web avec la variable d'environnement USE_SIMPLE_CSS_MINIFIER=true pour minifier les CSS avec le preset cssnano par défaut. Veuillez remplir une issuee si vous rencontrez des bugs de minification CSS.

docusaurus swizzle [siteDir]#

caution

Nous décourageons de « swizzler » des composants pendant la phase bêta du Docusaurus 2. Les API des composants de thèmes sont susceptibles d'évoluer et de subir des modifications. Si possible, restez avec l'apparence par défaut pour le moment.

Changez tous les composants du thème Docusaurus à votre goût avec npm run swizzle.

npm run swizzle [themeName] [componentName] [siteDir]
# Exemple (en omettant le siteDir pour indiquer ce répertoire)npm run swizzle @docusaurus/theme-classic DocSidebar

Exécuter la commande, copiera les fichiers de thème pertinents dans le dossier de votre site. Vous pouvez alors apporter des modifications et Docusaurus les utilisera à la place de celle fournie par le thème.

npm run swizzle sans themeName liste tous les thèmes disponibles pour le swizzle ; de la même manière, npm run swizzle<themeName> sans componentName liste tous les composants disponibles pour le swizzle.

Options#

NomDescription
themeNameLe nom du thème que vous utilisez.
swizzleComponentLe nom du composante pour la commande swizzle.
--dangerAutoriser le swizzle sur des composants instables
--typescriptSwizzle les composants TypeScript

Un exemple pour utiliser le drapeau --danger considérons le code ci-dessous :

npm run swizzle @docusaurus/theme-classic Logo -- --danger
caution

Composants instables : composants qui présentent un risque plus élevé de rupture des modifications en raison de remaniements internes.

Pour annuler le swizzle d'un composant, il suffit de supprimer les fichiers « swizzlé » du composant.

docusaurus deploy [siteDir]#

Déploie votre site avec GitHub Pages. Consultez la documentation sur le déploiement pour plus de détails.

Options#

NomPar défautDescription
--out-dirbuildLe chemin complet du nouveau répertoire de sortie, relatif à l'espace de travail actuel.
--skip-buildfalseDéploie le site sans le construire. Cela peut être utile lorsque vous utilisez un script de déploiement personnalisé.
--configundefinedChemin vers le fichier de configuration de docusaurus, par défaut [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]#

Sert votre site web construit localement.

NomPar défautDescription
--port3000Utiliser le port spécifié
--dirbuildLe chemin complet du répertoire de sortie, par rapport à l'espace de travail courant
--buildfalseConstruire le site web avant de le servir
--configundefinedChemin vers le fichier de configuration de docusaurus, par défaut [siteDir]/docusaurus.config.js
--hostlocalhostSpécifie un hôte à utiliser. Par exemple, si vous voulez que votre serveur soit accessible à l'extérieur, vous pouvez utiliser --host 0.0.0.0.

docusaurus clear [siteDir]#

Vide les ressources générées par le site Docusaurus, les caches, les artefacts de construction.

Nous vous recommandons d'exécuter cette commande avant de signaler des bogues, après la mise à niveau des versions, ou à chaque fois que vous avez des problèmes avec votre site Docusaurus.

docusaurus write-translations [siteDir]#

Écrit les fichiers de traduction JSON que vous devrez traduire.

Par défaut, les fichiers sont écrits dans website/i18n/<defaultLocale>/....

NomPar défautDescription
--locale<defaultLocale>Définissez le dossier de locale dans lequel vous voulez écrire les traductions des fichiers JSON
--overridefalseÉcrase les messages de traduction existants
--configundefinedChemin vers le fichier de configuration de docusaurus, par défaut [siteDir]/docusaurus.config.js
--messagePrefix''Permet d'ajouter un préfixe à chaque message de traduction, pour vous aider à mettre en évidence les chaînes non traduites

docusaurus write-heading-ids [siteDir]#

Ajoute des id de titre explicite aux documents Markdown de votre site.