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

플러그인

플러그인은 도큐사우루스 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개까지입니다.

플러그인 설계

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

플러그인 만들기

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

It returns a plugin instance object, containing plugin lifecycle APIs.

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

함수 정의

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

docusaurus.config.js
module.exports = {
// ...
plugins: [
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 파일 내에 설정할 수 있습니다. 플러그인에 프리셋이 포함되어 있다면 프리셋이 정확한 옵션 설정을 플러그인에 전달할 수 있게 합니다. 어떤 옵션을 설정하도록 허용할지는 각 플러그인을 만들 때 결정합니다.

반환값

The returned object value should implement the lifecycle APIs.