확장 구조

도큐사우루스는 외부 플러그인으로 확장할 수 있는 핫 리로딩, CLI, 스위즐링 같은 일부 구조를 가지고 있습니다.

getPathsToWatch()

플러그인과 테마 변경을 체크하기 위한 경로를 설정합니다. 설정된 경로는 개발 서버에서 지켜보고 있다가 내용 변경이 생기면 플러그인 수명주기가 다시 로드됩니다. 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.

테마 파일은 웹팩 개발 서버에서 지켜보고 있기 때문에 이건 서버 측에서 사용하는 파일을 위해 사용합니다.

예:

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)

도큐사우루스의 명령행 인터페이스를 확장하기 위한 추가 명령어를 등록합니다. cli is a Commander 15 Command object.

예:

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()

테마 컴포넌트를 찾을 수 있는 디렉터리 경로를 반환합니다. When your users call swizzle, getThemePath is called and its returned path is used to find your theme components. 엔트리 포인트가 포함된 폴더에 대해 상대 경로를 확인합니다.

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 the bundler. 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.

팁

타입스크립트 테마 작성 시에 컴파일된 출력 결과를 사람이 읽을 수 있도록 만드는 것이 좋습니다. Only strip type annotations and don't transpile any syntaxes, because Docusaurus transpiles them based on the targeted browser versions.

Prettier 같은 도구를 사용해 이런 파일 포맷을 정리해야 합니다. 잊지마세요. JS 파일은 사용자가 직접 사용할 수 있으며 사용할 것입니다.

예:

my-theme/src/index.js

export default function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      // Where compiled JavaScript output lives
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // Where TypeScript source code lives
      return '../src/theme';
    },
  };
}

getSwizzleConfig()

This is a static method, not attached to any plugin instance. Export it from the theme module, or attach it to the plugin constructor function.

Returns the swizzle config of the theme, declaring how safe it is to swizzle each theme component:

type SwizzleConfig = {
  components: {
    [componentName: string]: {
      actions: {
        eject: 'safe' | 'unsafe' | 'forbidden';
        wrap: 'safe' | 'unsafe' | 'forbidden';
      };
      description?: string;
    };
  };
};

• componentName: the name of the theme component, relative to the theme path, such as Footer or Admonition/Icon.
• actions: the safety status of each swizzle action. Actions not provided are unsafe.
• description: a description of the component, displayed by docusaurus swizzle --list.

Components not listed are unsafe to eject and to wrap.

my-theme/src/index.js

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

export function getSwizzleConfig() {
  return {
    components: {
      Footer: {
        actions: {
          eject: 'safe',
          wrap: 'safe',
        },
        description: "The footer component of your site's layout",
      },
      DocSidebar: {
        actions: {
          eject: 'unsafe',
          wrap: 'safe',
        },
        description: 'The sidebar component on docs pages',
      },
      'prism-include-languages': {
        actions: {
          eject: 'safe',
          wrap: 'forbidden', // Not a component!
        },
      },
    },
  };
}

getSwizzleComponentList()

Deprecated

Use getSwizzleConfig() instead.

A static method returning the list of components that are safe to eject and to wrap. It is ignored when the theme provides getSwizzleConfig().