버전: Canary 🚧

플러그인

Plugins are the building blocks of features in a Docusaurus site. 각 플러그인은 개별적인 기능을 가지고 있습니다. 플러그인은 presets을 통해 전체 묶음의 일부로 동작하고 배포됩니다.

플러그인 만들기

플러그인은 context와 options 2개의 파라미터를 가지는 함수입니다. 플러그인 인스턴스 오브젝트(또는 프로미스)를 반환합니다. 플러그인은 함수 또는 모듈로 만들 수 있습니다. 좀 더 자세한 내용은 플러그인 메소드 참조 항목을 참고하세요.

함수 정의

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

docusaurus.config.js
export default {
  // ...
  plugins: [
    async function myPlugin(context, options) {
      // ...
      return {
        name: 'my-plugin',
        async loadContent() {
          // ...
        },
        async contentLoaded({content, actions}) {
          // ...
        },
        /* 다른 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 같은 작업을 통해 클라이언트 측에서 데이터를 사용할 수 있습니다. 데이터는 플러그인과 테마가 다른 환경에서 실행되기 때문에 일반 문자열로 _직렬화_되어야 합니다. 데이터가 클라이언트 측에 도착하면 나머지는 리액트 개발자에게 익숙한 과정입니다. 데이터는 컴포넌트를 따라 전달되고 컴포넌트는 웹팩과 번들로 제공되며 ReactDOM.render를 통해 화면에 렌더링됩니다.

테마는 컨텐츠를 화면에 표시하기 위해 제공되는 UI 컴포넌트입니다. 대부분의 컨텐츠 플러그인을 실제 사용하기 위해서는 테마가 같이 제공되어야 합니다. UI는 데이터 스키마와 별도의 레이어이므로 디자인을 쉽게 교체할 수 있습니다.

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

노트

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

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

부트스트랩 테마를 사용하고 싶다면 theme-blog-bootstrap(실제 있는 테마는 아닙니다)로 설정값을 변경하기만 하면 됩니다.

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

이제 테마가 플러그인에서 같은 데이터를 수신하더라도 테마에서 데이터를 UI로 _렌더링_하도록 선택하는 방법은 극적으로 달라집니다.

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

테마는 여러분이 도큐사우루스 사이트를 빌드하고 사이트, 플러그인, 테마 자신이 사용할 수 있는 컴포넌트를 공급하도록 설계됩니다. 테마는 여전히 플러그인처럼 작동하고 일부 수명 주기 메소드를 노출하지만 플러그인에서는 데이터만 수신하고 데이터 자체를 생성하지는 않기 때문에 loadContent를 사용하지 않을 가능성이 큽니다. 테마는 일반적으로 getThemePath 수명 주기를 통해 코어에 알려진 컴포넌트로 가득찬 src/theme 디렉터리와 함께 제공됩니다.

다시 정리하면

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

플러그인

플러그인 만들기​

함수 정의​

모듈 정의​

플러그인 설계​

테마 설계​

플러그인 만들기

함수 정의

모듈 정의

플러그인 설계

테마 설계