플러그인 메소드 참고

warning

Lifecycle API는 아직 개발 진행중입니다. 문서 내 링크나 외부 URL도 아직 안정적이지 않을 수 있습니다.

플러그인 API는 테마와 플러그인에서 공유됩니다. 테마는 플러그인처럼 로드됩니다.

Plugin module

모든 플러그인은 모듈 형태로 가져옵니다. 모듈에는 다음과 같은 요소가 필요합니다.

• A default export: the constructor function for the plugin.
• Named exports: the static methods called before plugins are initialized.

Plugin constructor

The plugin module's default export is a constructor function with the signature (context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>.

context

context is plugin-agnostic, and the same object will be passed into all plugins used for a Docusaurus website. The context object contains the following fields:

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

options

options are the second optional parameter when the plugins are used. options are plugin-specific and are specified by users when they use them in docusaurus.config.js. If there's a validateOptions function exported, the options will be validated and normalized beforehand.

플러그인에 프리셋이 포함되어 있다면 프리셋이 정확한 옵션 설정을 플러그인에 전달할 수 있게 합니다. 어떤 옵션을 설정하도록 허용할지는 각 플러그인을 만들 때 결정합니다.

Example

아래 코드는 모든 기능을 사용한 플러그인 구현을 위한 멘탈 모델입니다.

// 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
    },

    // TODO
    afterDevServer(app, server) {
      // https://webpack.js.org/configuration/dev-server/#devserverbefore
    },

    // TODO
    beforeDevServer(app, server) {
      // https://webpack.js.org/configuration/dev-server/#devserverafter
    },

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