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"
  }
}

Commandes CLI Docusaurus

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

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.
--locale		Spécifie la locale du site à utiliser.
--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 la page automatiquement 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.
--https	false	Serve the dev site over HTTPS using a self-signed certificate. Implied when both --ssl-cert and --ssl-key are provided.
--ssl-cert	undefined	Path to a TLS certificate file (implies HTTPS).
--ssl-key	undefined	Path to a TLS private key file (implies HTTPS).

info

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.

Développement sur le réseau

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

npm run start -- --host 0.0.0.0

Yarn

yarn run start --host 0.0.0.0

pnpm

pnpm run start --host 0.0.0.0

Bun

bun run start --host 0.0.0.0

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. Start the app with the Docusaurus HTTPS CLI options:

npm

npm run start -- --ssl-cert localhost.pem --ssl-key localhost-key.pem

Yarn

yarn run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

pnpm

pnpm run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

Bun

bun run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

4. Ouvrez https://localhost:3000/

Self-signed certificate

Use the --https option to serve the dev site over HTTPS with an automatically generated self-signed certificate:

npm

npm run start -- --https

Yarn

yarn run start --https

pnpm

pnpm run start --https

Bun

bun run start --https

docusaurus build [siteDir]

Compile votre site pour la production.

Options

Nom	Par défaut	Description
--dev		Construit le site web en mode dev, y compris les messages d'erreur React complets.
--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
--locale		Build the site in the specified locale(s). Si non spécifié, toutes les locales connues sont construites.
--no-minify	false	Construit un site web sans minimiser les bundles JS/CSS.

info

CSS bundles are minified with Lightning CSS, using your site's Browserslist config as targets. Please fill out an issue if you experience CSS minification bugs.

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

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

yarn swizzle [themeName] [componentName] [siteDir]

# Exemple (en omettant le siteDir pour indiquer ce répertoire)
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

pnpm run swizzle [themeName] [componentName] [siteDir]

# Exemple (en omettant le siteDir pour indiquer ce répertoire)
pnpm run swizzle @docusaurus/theme-classic Footer --eject

Bun

bun run swizzle [themeName] [componentName] [siteDir]

# Exemple (en omettant le siteDir pour indiquer ce répertoire)
bun 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
--javascript	Swizzle the JavaScript variant component
--config	Chemin vers le fichier de config de Docusaurus, par défaut [siteDir]/docusaurus.config.js

attention

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. Check out the docs on deployment for more details.

Options

Nom	Par défaut	Description
--locale		Deploy the site in the specified locale(s). Si non spécifié, toutes les locales connues sont déployées.
--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é.
--target-dir	.	Chemin du répertoire cible vers lequel le déploiement doit s'effectuer.
--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.

HTTP caching

docusaurus serve tells browsers how to cache each response with the Cache-Control header:

Responses	Cache-Control	Browser behavior
Files in /assets/	public, max-age=31536000, immutable	Reuses the file for one year, without asking the server.
Everything else: pages, other static files, redirects, errors	no-cache	Asks the server before each reuse. The server answers 304 Not Modified when the file content didn't change, using its ETag.

The bundler adds a content hash to the names of the files it emits in /assets/ (JavaScript, CSS, images, fonts…): when the content of a file changes, its URL changes too.

The other files keep their URLs from one build to the next. Revalidating them ensures you always see your latest build, and the redirects of your current baseUrl and trailingSlash config, even after serving another site on the same port.

The /assets/ folders of the other locales of an i18n site, like /fr/assets/, are revalidated like the other files.

attention

Don't put files in an assets folder of your static directories, like static/assets/. They are copied to /assets/ without a content hash, so browsers can keep using an outdated version for one year.

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.
--syntax	Inferred	Heading ID syntax to use: classic ({#id}) or mdx-comment ({/* #id */}). By default, it uses classic for files compiled as CommonMark, and mdx-comment for files compiled as MDX, according to the markdown.format config option.
--migrate	false	Migrate existing heading IDs to the target --syntax, if they are using a different syntax.
--overwrite	false	Overwrite existing heading IDs, re-generate them from the heading text.
--maintain-case	false	Conserve la casse des entêtes, sinon met tout en minuscules.