Références de Méthode de Plugin

attention

Cette section est en cours de rédaction. La stabilité des liens d'ancrage ou même des URL n'est pas garantie.

Les API de plugins sont partagées par les thèmes et les plugins — les thèmes sont chargés comme les plugins.

Module de plugin

Chaque plugin est importé en tant que module. Le module devrait avoir les membres suivants :

• Un default export : la fonction constructeur du plugin.
• Exports nommés : les méthodes statiques appelées avant que les plugins ne soient initialisés.

Constructeur de plugin

L'export par défaut du module du plugin est une fonction constructeur avec la signature (context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>.

context

context est agnostique par rapport aux plugins et le même objet sera passé dans tous les plugins utilisés pour un site web Docusaurus. L'objet context contient les champs suivants :

type LoadContext = {
  siteDir: string;
  generatedFilesDir: string;
  siteConfig: DocusaurusConfig;
  outDir: string;
  baseUrl: string;
};

options

options sont le second paramètre optionnel lorsque les plugins sont utilisés. options est spécifique à un plugin et est spécifié par les utilisateurs lorsqu'ils les utilisent dans docusaurus.config.js. S'il y a une fonction validateOptions exportée, les options seront validées et normalisées au préalable.

En revanche, si un preset contient le plugin, le preset se chargera alors de passer les bonnes options au plugin. Il appartient au plugin de définir les options qu'il prend.

Exemple

Voici un modèle de pensée pour une implémentation présumée d'un plugin.

// A JavaScript function that returns an object.
// `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
// `opts` is the user-defined options.
export default async function myPlugin(context, opts) {
  return {
    // A compulsory field used as the namespace for directories to cache
    // the intermediate data for each plugin.
    // If you're writing your own local plugin, you will want it to
    // be unique in order not to potentially conflict with imported plugins.
    // A good way will be to add your own project name within.
    name: 'docusaurus-my-project-cool-plugin',

    async loadContent() {
      // The loadContent hook is executed after siteConfig and env has been loaded.
      // You can return a JavaScript object that will be passed to contentLoaded hook.
    },

    async contentLoaded({content, actions}) {
      // The contentLoaded hook is done after loadContent hook is done.
      // `actions` are set of functional API provided by Docusaurus (e.g. addRoute)
    },

    async postBuild(props) {
      // After docusaurus <build> finish.
    },

    // TODO
    async postStart(props) {
      // docusaurus <start> finish
    },

    configureWebpack(config, isServer, utils, content) {
      // Modify internal webpack config. If returned value is an Object, it
      // will be merged into the final config using webpack-merge;
      // If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
    },

    getPathsToWatch() {
      // Paths to watch.
    },

    getThemePath() {
      // Returns the path to the directory where the theme components can
      // be found.
    },

    getClientModules() {
      // Return an array of paths to the modules that are to be imported
      // in the client bundle. These modules are imported globally before
      // React even renders the initial UI.
    },

    extendCli(cli) {
      // Register an extra command to enhance the CLI of Docusaurus
    },

    injectHtmlTags({content}) {
      // Inject head and/or body HTML tags.
    },

    async getTranslationFiles({content}) {
      // Return translation files
    },

    translateContent({content, translationFiles}) {
      // translate the plugin content here
    },

    translateThemeConfig({themeConfig, translationFiles}) {
      // translate the site themeConfig here
    },

    async getDefaultCodeTranslationMessages() {
      // return default theme translations here
    },
  };
}

export function validateOptions({options, validate}) {
  const validatedOptions = validate(myValidationSchema, options);
  return validatedOptions;
}

export function validateThemeConfig({themeConfig, validate}) {
  const validatedThemeConfig = validate(myValidationSchema, options);
  return validatedThemeConfig;
}