Extension de l'infrastructure

Docusaurus dispose de certaines infrastructures comme le rechargement à chaud, le CLI et le swizzling, qui peuvent être étendues par des plugins externes.

getPathsToWatch()

Spécifie les chemins à surveiller pour les plugins et les thèmes. Les chemins sont surveillés par le serveur de développement de sorte que les cycles de vie du plugin sont rechargés lorsque le contenu des chemins surveillés change. Note that the plugins and themes modules are initially called with context and options from Node, which you may use to find the necessary directory information about the site.

Utilisez cette option pour les fichiers qui sont consommés côté serveur, car les fichiers de thème sont automatiquement surveillés par le serveur de développement Webpack.

Exemple :

docusaurus-plugin/src/index.js

import path from 'path';

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    getPathsToWatch() {
      const contentPath = path.resolve(context.siteDir, options.path);
      return [`${contentPath}/**/*.{ts,tsx}`];
    },
  };
}

extendCli(cli)

Enregistre une commande supplémentaire pour améliorer la CLI de Docusaurus. cli is a commander object.

attention

La version du commander est importante ! Nous utilisons commander v5, et assurez-vous que vous vous référez à la documentation de la bonne version pour les API disponibles.

Exemple :

docusaurus-plugin/src/index.js

export default function (context, options) {
  return {
    name: 'docusaurus-plugin',
    extendCli(cli) {
      cli
        .command('roll')
        .description('Roll a random number between 1 and 1000')
        .action(() => {
          console.log(Math.floor(Math.random() * 1000 + 1));
        });
    },
  };
}

getThemePath()

Retourne le chemin vers le répertoire où les composants du thème peuvent être trouvés. When your users call swizzle, getThemePath is called and its returned path is used to find your theme components. Les chemins relatifs sont résolus par rapport au dossier contenant le point d'entrée.

For example, your getThemePath can be:

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      return './theme';
    },
  };
}

getTypeScriptThemePath()

Similar to getThemePath(), it should return the path to the directory where the source code of TypeScript theme components can be found. This path is purely for swizzling TypeScript theme components, and theme components under this path will not be resolved by Webpack. Therefore, it is not a replacement for getThemePath(). Typically, you can make the path returned by getTypeScriptThemePath() be your source directory, and make the path returned by getThemePath() be the compiled JavaScript output.

astuce

Pour les auteurs de thèmes TypeScript : il est fortement conseillé de rendre votre sortie compilée aussi lisible que possible par l'homme. Ne retirez que les annotations de type et ne transposez aucune syntaxe, car elles seront traitées par le chargeur Babel de Webpack en fonction des versions des navigateurs ciblés.

Vous devriez également formater ces fichiers avec Prettier. Rappelez-vous : les fichiers JS peuvent et seront consommés directement par vos utilisateurs.

Exemple :

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      // Où se trouve la sortie JavaScript compilée
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // Où se trouve le code source de TypeScript
      return '../src/theme';
    },
  };
}

getSwizzleComponentList()

This is a static method, not attached to any plugin instance.

Retourne une liste de composants stables considérés comme sûrs pour le swizzle. These components will be swizzlable without --danger. Tous les composants sont considérés comme instables par défaut. Si un tableau vide est retourné, tous les composants sont considérés comme instables. If undefined is returned, all components are considered stable.

my-theme/src/index.js

export function getSwizzleComponentList() {
  return [
    'CodeBlock',
    'DocSidebar',
    'Footer',
    'NotFound',
    'SearchBar',
    'hooks/useTheme',
    'prism-include-languages',
  ];
}