버전: 3.10.2

플러그인

플러그인은 도큐사우루스 사이트의 기능을 구성하는 기본 요소입니다. 각 플러그인은 개별적인 기능을 가지고 있습니다. 플러그인은 presets을 통해 전체 묶음의 일부로 동작하고 배포됩니다.

플러그인 만들기

플러그인은 context와 options 두 매개변수를 받는 함수입니다. 플러그인 인스턴스 오브젝트(또는 프로미스)를 반환합니다. 플러그인은 함수 또는 모듈로 만들 수 있습니다. 자세한 내용은 플러그인 메서드 참고 문서를 확인하세요.

함수 정의

도큐사우루스 설정 파일을 아래와 같이 지정하면 플러그인을 함수처럼 사용할 수 있습니다.

docusaurus.config.js
export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* other lifecycle API */
      };
    },
  ],
};

모듈 정의

별도 파일 또는 npm 패키지를 참조하는 모듈 경로로 플러그인을 사용할 수 있습니다.

docusaurus.config.js
export default {
  // ...
  plugins: [
    // without options:
    './my-plugin',
    // or with options:
    ['./my-plugin', options],
  ],
};

그런 다음 my-plugin 폴더에 다음과 같은 index.js를 만들 수 있습니다:

my-plugin/index.js
export default async function myPlugin(context, options) {
  // ...
  return {
    name: 'my-plugin',
    async loadContent() {
      /* ... */
    },
    async contentLoaded({content, actions}) {
      /* ... */
    },
    /* other lifecycle API */
  };
}

디버그 플러그인의 메타데이터 패널에서 사이트에 설치된 모든 플러그인을 볼 수 있습니다.

플러그인은 몇 가지 유형으로 제공됩니다.

package: 설치한 외부 패키지
project: 프로젝트 안에서 직접 만들고 로컬 파일 경로로 도큐사우루스에 전달한 플러그인
local: 함수 정의를 사용해 만든 플러그인
synthetic: 도큐사우루스가 내부적으로 생성한 "가상 플러그인"입니다. 모듈식 구조를 활용하여 코어가 특별한 작업을 너무 많이 담당하지 않도록 합니다. 구현 세부 사항이기 때문에 메타데이터에서 확인할 수 없습니다.

클라이언트 측에서 useDocusaurusContext().siteMetadata.pluginVersions로 접근할 수 있습니다.

플러그인 설계

도큐사우루스에서 구현한 플러그인 시스템은 페이지에서 사용할 수 있는 새로운 컴포넌트를 만들거나 설정을 확장하고 불러오는 데이터를 가공할 수 있도록(그리고 더 많은 일을 할 수 있게) 지원합니다. 플러그인은 웹 사이트를 개발하거나 빌드할 때 손쉽게 사용할 수 있도록 구현할 수 있습니다.

테마 설계

플러그인이 콘텐츠를 로드하면 createData + addRoute 또는 setGlobalData 같은 액션을 통해 데이터를 클라이언트 측에 제공합니다. 플러그인과 테마는 서로 다른 환경에서 실행되므로 이 데이터는 일반 문자열로 _직렬화_해야 합니다. 데이터가 클라이언트 측에 도착한 이후의 과정은 리액트 개발자에게 익숙할 것입니다. 데이터가 컴포넌트로 전달되고, 컴포넌트는 Webpack으로 번들링되며, ReactDOM.render를 통해 화면에 렌더링됩니다...

테마는 콘텐츠를 렌더링할 UI 컴포넌트 모음을 제공합니다. 대부분의 콘텐츠 플러그인은 실제로 활용하려면 테마와 함께 사용해야 합니다. UI는 데이터 스키마와 별도의 레이어이므로 디자인을 쉽게 교체할 수 있습니다.

예를 들어 도큐사우루스 블로그는 블로그 플러그인과 블로그 테마로 구성이 되어 있습니다.

참고

이는 설명을 위해 만든 예제입니다. 실제로는 @docusaurus/theme-classic이 문서, 블로그, 레이아웃의 테마를 제공합니다.

docusaurus.config.js
export default {
  themes: ['theme-blog'],
  plugins: ['plugin-content-blog'],
};

Bootstrap 스타일을 사용하려면 테마를 theme-blog-bootstrap(실제로 존재하지 않는 또 다른 예시 테마)으로 바꿀 수 있습니다:

docusaurus.config.js
export default {
  themes: ['theme-blog-bootstrap'],
  plugins: ['plugin-content-blog'],
};

이제 테마가 플러그인에서 같은 데이터를 받더라도 데이터를 UI로 _렌더링_하는 방식은 완전히 다를 수 있습니다.

테마는 플러그인과 같은 lifecyelc 메소드를 공유합니다. 하지만 테마의 설계 목적에 따라 플러그인과 구현 방식은 달라질 수 있습니다.

테마는 여러분이 도큐사우루스 사이트를 빌드하고 사이트, 플러그인, 테마 자신이 사용할 수 있는 컴포넌트를 공급하도록 설계됩니다. 테마도 플러그인처럼 동작하고 일부 수명 주기 메서드를 제공합니다. 하지만 플러그인에서 데이터를 받을 뿐 직접 생성하지는 않으므로 대부분 loadContent를 사용하지 않습니다. 또한 테마에는 보통 컴포넌트가 담긴 src/theme 디렉터리가 있으며, getThemePath 수명 주기를 통해 코어에 알려집니다.

다시 정리하면

테마는 플러그인과 같은 lifecycle 메소드를 공유합니다.
테마는 모든 플러그인이 설정된 이후 동작합니다.
테마는 getThemePath를 제공하여 컴포넌트 별칭을 추가합니다.

플러그인 만들기​

함수 정의​

모듈 정의​

플러그인 설계​

테마 설계​

플러그인 만들기

함수 정의

모듈 정의

플러그인 설계

테마 설계