확장 구조

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

getPathsToWatch()

플러그인과 테마 변경을 체크하기 위한 경로를 설정합니다. 설정된 경로는 개발 서버에서 지켜보고 있다가 내용 변경이 생기면 플러그인 수명주기가 다시 로드됩니다. 초기 설정된 플러그인과 테마 모듈은 노드 상에서 context와 options를 사용해 접근할 수 있습니다. 이를 통해 필요한 디렉터리 정보를 얻을 수 있습니다.

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

예:

docusaurus-plugin/src/index.js

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

extendCli(cli)

도큐사우루스의 명령행 인터페이스를 확장하기 위한 추가 명령어를 등록합니다. cli는 commander 오브젝트입니다.

warning

commander 버전 관련 이슈가 있습니다. 우리는 commander v5를 사용하며 사용할 수 있는 API에 대한 올바른 버전 문서를 참고하고 있는지 확인합니다.

예:

docusaurus-plugin/src/index.js

module.exports = 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()

테마 컴포넌트를 찾을 수 있는 디렉터리 경로를 반환합니다. 사용자가 swizzle을 호출하면 getThemePath가 호출되면서 테마 컴포넌트를 찾을 수 있는 경로를 반환합니다. 엔트리 포인트가 포함된 폴더에 대해 상대 경로를 확인합니다.

예를 들어 getThemePath는 이렇게 설정할 수 있습니다.

my-theme/src/index.js

const path = require('path');

module.exports = function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      return './theme';
    },
  };
};

getTypeScriptThemePath()

getThemePath()와 비슷하게 타입스크립트 테마 컴포넌트 소스 코드를 찾을 수 있는 디렉터리 경로를 반환합니다. 이 경로는 순전히 타입스크립트 테마 컴포넌트를 스위즐링하기 위한 것이며 해당 경로 아래의 테마 컴포넌트는 웹팩에서 처리하지 않습니다. 그래서 getThemePath() 기능을 대체하는 것은 아닙니다. 보통의 경우 getTypeScriptThemePath()에서 반환된 경로를 소스 디렉터리로 설정하고 getThemePath()에서 반환된 경로를 컴파일된 자바스크립트 출력 경로로 설정합니다.

팁

타입스크립트 테마 작성 시에 컴파일된 출력 결과를 사람이 읽을 수 있도록 만드는 것이 좋습니다. 브라우저에 따라 웹팩의 Babel 로더가 처리하기 때문에 타입 표기만 제거하고 구문은 변환하지 마세요.

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

예:

my-theme/src/index.js

const path = require('path');

module.exports = function (context, options) {
  return {
    name: 'my-theme',
    getThemePath() {
      // 컴파일된 자바스크립트 산출물 위치
      return '../lib/theme';
    },
    getTypeScriptThemePath() {
      // 타입스크립트 소스 코드 위치
      return '../src/theme';
    },
  };
};

getSwizzleComponentList()

플러그인 인스턴스에 연결되지 않은 정적 메소드입니다.

안전하게 스위즐링을 처리할 수 있는 안정적인 컴포넌트 목록을 반환합니다. 해당 컴포넌트는 --danger 옵션을 사용하지 않고 스위즐링을 처리할 수 있습니다. 기본적으로 모든 컴포넌트는 안정적이지 않는 것으로 여깁니다. 빈 배열값이 반환되면 모든 컴포넌트가 불안정적인 것으로 간주됩니다. undefined 값이 반환되면 모든 컴포넌트가 안정적인 것으로 간주됩니다.

my-theme/src/index.js

const swizzleAllowedComponents = [
  'CodeBlock',
  'DocSidebar',
  'Footer',
  'NotFound',
  'SearchBar',
  'hooks/useTheme',
  'prism-include-languages',
];

myTheme.getSwizzleComponentList = () => swizzleAllowedComponents;