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 :
{
// ...
"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"
}
}
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
Nom | Par défaut | Description |
---|---|---|
--port | 3000 | Spécifie le port du serveur dev. |
--host | localhost | Spé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-only | false | Active le remplacement des modules à chaud sans rafraîchissement de page en cas d'échec de construction. Plus d'informations ici. |
--no-open | false | N'ouvre pas automatiquement la page dans le navigateur. |
--config | undefined | Chemin vers le fichier de configuration de Docusaurus, par défaut [siteDir]/docusaurus.config.js |
--poll [optionalIntervalMs] | false | Utilisez 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. |
--no-minify | false | Construit un site web sans minimiser les bundles JS/CSS. |
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.
Lorsque vous transférez le port 3000 à partir d'un serveur ou d'une VM distante (par exemple, GitHub Codespaces), vous pouvez exécuter le serveur de développement sur 0.0.0.0
pour qu'il écoute sur l'IP locale.
- npm
- Yarn
- pnpm
npm run start -- --host 0.0.0.0
yarn run start --host 0.0.0.0
pnpm run start -- --host 0.0.0.0
Activation HTTPS
Il y a plusieurs façons d'obtenir un certificat. Nous utiliserons mkcert comme exemple.
-
Exécutez
mkcert localhost
pour générerlocalhost.pem
+localhost-key.pem
-
Exécutez
mkcert -install
pour installer le cert dans votre magasin de confiance, et redémarrez votre navigateur -
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
- Ouvrez
https://localhost:3000/
docusaurus build [siteDir]
Compile votre site pour la production.
Options
Nom | Par défaut | Description |
---|---|---|
--bundle-analyzer | false | Analyse votre bundle avec l'analyseur de bundle de webpack. |
--out-dir | build | Le chemin complet du nouveau répertoire de sortie, relatif à l'espace de travail actuel. |
--config | undefined | Chemin vers le fichier de configuration de Docusaurus, par défaut [siteDir]/docusaurus.config.js |
--no-minify | false | Construit un site web sans minimiser les bundles JS/CSS. |
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.
Vous pouvez passer la minification HTML avec la variable d'environnement SKIP_HTML_MINIFICATION=true
.
docusaurus swizzle [themeName] [componentName] [siteDir]
Swizzlez un composant de thème pour le personnaliser.
- npm
- Yarn
- pnpm
npm run swizzle [themeName] [componentName] [siteDir]
# Exemple (en omettant le siteDir pour indiquer ce répertoire)
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle [themeName] [componentName] [siteDir]
# Exemple (en omettant le siteDir pour indiquer ce répertoire)
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle [themeName] [componentName] [siteDir]
# Exemple (en omettant le siteDir pour indiquer ce répertoire)
pnpm run swizzle @docusaurus/theme-classic Footer -- --eject
Le CLI du swizzle est interactif et vous guidera à travers tout le processus du swizzle.
Options
Nom | Description |
---|---|
themeName | Le nom du thème à swizzler. |
componentName | Le nom du composant du thème à swizzler. |
--list | Affiche les composants disponibles pour le swizzling |
--eject | Éjecte le composant du thème |
--wrap | Enveloppe le composant du thème |
--danger | Autorise le swizzling immédiatement sur des composants instables |
--typescript | Swizzle le composant de type TypeScript |
Les composants non sécurisés présentent un risque plus élevé de rupture des modifications dues à des remaniements internes.
docusaurus deploy [siteDir]
Déploie votre site avec GitHub Pages. Consultez la documentation sur le déploiement pour plus de détails.
Options
Nom | Par défaut | Description |
---|---|---|
--out-dir | build | Le chemin complet du nouveau répertoire de sortie, relatif à l'espace de travail actuel. |
--skip-build | false | Déploie le site sans le construire. Cela peut être utile lorsque vous utilisez un script de déploiement personnalisé. |
--config | undefined | Chemin vers le fichier de configuration de Docusaurus, par défaut [siteDir]/docusaurus.config.js |
docusaurus serve [siteDir]
Sert votre site web construit localement.
Nom | Par défaut | Description |
---|---|---|
--port | 3000 | Utiliser le port spécifié |
--dir | build | Le chemin complet du répertoire de sortie, par rapport à l'espace de travail courant |
--build | false | Construire le site web avant de le servir |
--config | undefined | Chemin vers le fichier de configuration de Docusaurus, par défaut [siteDir]/docusaurus.config.js |
--host | localhost | Spé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 . |
--no-open | false localement, true dans le CI | N'ouvrez pas une fenêtre de navigateur à l'emplacement du serveur. |
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>/...
.
Nom | Par défaut | Description |
---|---|---|
--locale | <defaultLocale> | Définissez le dossier de locale dans lequel vous voulez écrire les traductions des fichiers JSON |
--override | false | Écrase les messages de traduction existants |
--config | undefined | Chemin 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] [files]
Ajoute des ID de titre explicite aux documents Markdown de votre site.
Nom | Par défaut | Description |
---|---|---|
files | Tous les fichiers MD utilisés par les plugins | Les fichiers dans lesquels vous voulez que les ID d'entête soient écrits. |
--maintain-case | false | Conserve la casse des entêtes, sinon met tout en minuscules. |
--overwrite | false | Écrase les ID d'entête existants. |