메인 컨텐츠로 이동
Version: 2.0.0-beta.3

플러그인

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

사용할 수 있는 플러그인#

공식 지원 플러그인 목록에서 도큐사우루스에서 관리하는 플러그인을 확인할 수 있습니다. 하지만 일부 플러그인은 커뮤니티 내에서 만들어지기도 합니다. 비공식 플러그인을 참고하세요.

플러그인 설치하기#

플러그인은 npm 패키지 형태로 제공됩니다. npm을 사용해 다른 npm 패키지처럼 설치할 수 있습니다.

npm install --save docusaurus-plugin-name

설치 후에는 docusaurus.config.js 파일에서 plugins 옵션을 설정합니다.

docusaurus.config.js
module.exports = {  // ...  plugins: ['@docusaurus/plugin-content-pages'],};

도큐사우루스는 로컬 디렉터리에서 플러그인을 불러올 수도 있습니다. 다음과 같이 설정합니다.

docusaurus.config.js
const path = require('path');
module.exports = {  // ...  plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],};

플러그인 설정하기#

대부분 플러그인을 기본적으로 사용하려면 플러그인 이름과 플러그인이 설치된 절대 경로를 설정해주어야 합니다.

하지만 플러그인은 설정 시 이름과 옵션 오브젝트를 배열 형태로 감싸서 설정할 수 있는 기능을 지원합니다. 이런 형식을 Babel Style이라고 합니다.

docusaurus.config.js
module.exports = {  // ...  plugins: [    [      '@docusaurus/plugin-xxx',      {        /* options */      },    ],  ],};

예를 들면 아래와 같이 설정합니다.

docusaurus.config.js
module.exports = {  plugins: [    // Basic usage.    '@docusaurus/plugin-google-analytics',
    // With options object (babel style)    [      '@docusaurus/plugin-sitemap',      {        changefreq: 'weekly',      },    ],  ],};

멀티 인스턴스 플러그인과 플러그인 id#

모든 도큐사우루스 콘텐츠 플러그인은 멀티 플러그인 인스턴스를 지원합니다.

문서 플러그인은 추가적인 멀티 인스턴스 문서화를 지원합니다.

각 플러그인 인스턴스는 고유한 id값이 필요합니다.

플러그인 id 기본값은 default입니다.

docusaurus.config.js
module.exports = {  plugins: [    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-1',        // other options      },    ],    [      '@docusaurus/plugin-xxx',      {        id: 'plugin-xxx-2',        // other options      },    ],  ],};
note

id 속성을 지정하지 않거나 id: 'default'로 설정해서 "기본 플러그인 인스턴스"로 설정할 수 있는 건 최대 1개까지입니다.

플러그인 설계#

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

플러그인 만들기#

플러그인은 context와 options 2개의 파라미터를 가지는 함수입니다.

이 함수는 플러그인 lifecycle API를 포함하는 플러그인 인스턴스 오브젝트를 반환합니다.

함수 또는 모듈로 정의할 수 있습니다.

함수 정의#

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

docusaurus.config.js
module.exports = {  // ...  plugins: [    // highligh-start    function myPlugin(context, options) {      // ...      return {        name: 'my-plugin',        async loadContent() {          // ...        },        async contentLoaded({content, actions}) {          // ...        },        /* 다른 lifecycle API */      };    },  ],};

모듈 정의#

플러그인을 모듈처럼 사용해서 별도의 파일이나 NPM 패키지에서 로드할 수 있습니다.

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

my-plugin 디렉터리 안에 아래와 같이 index.js 파일을 만들 수 있습니다.

my-plugin.js
module.exports = function myPlugin(context, options) {  // ...  return {    name: 'my-plugin',    async loadContent() {      /* ... */    },    async contentLoaded({content, actions}) {      /* ... */    },    /* 다른 lifecycle API */  };};

context#

context는 플러그인과 별개이며 같은 오브젝트를 도큐사우루스 웹 사이트 전체에서 사용합니다. context 오브젝트는 다음과 같은 필드를 가지고 있습니다:

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

options#

options은 플러그인에서 선택적으로 사용하는 두 번째 파라미터입니다. options은 플러그인마다 정의되어 있으며 사용자가 필요할 때 docusaurus.config.js 파일 내에 설정할 수 있습니다. 플러그인에 프리셋이 포함되어 있다면 프리셋이 정확한 옵션 설정을 플러그인에 전달할 수 있게 합니다. 어떤 옵션을 설정하도록 허용할지는 각 플러그인을 만들 때 결정합니다.

반환값#

반환된 오브젝트는 lifecycle APIs를 구현한 오브젝트여야 합니다.