플러그인 사용하기

도큐사우루스 코어는 자체 기능을 제공하지 않습니다. 모든 기능은 개별 플러그인에 위임됩니다. docs는 문서 플러그인에서 제공하는 기능을 사용하고 blog는 블로그 플러그인에서 제공하는 기능을 사용하며 개별 pages는 페이지 플러그인에서 제공하는 기능을 사용합니다. 플러그인이 설치되어 있지 않으면 사이트에 어떤 경로도 포함할 수 없습니다.

공통으로 사용하는 플러그인을 하나씩 설치할 필요는 없습니다. preset 번들로 배포할 수 있습니다. 대부분 사용자의 경우 플러그인은 사전 설정된 구성을 통해 제공됩니다.

공식 지원 플러그인 목록에서 도큐사우루스에서 관리하는 플러그인을 확인할 수 있습니다. 하지만 일부 플러그인은 커뮤니티 내에서 만들어지기도 합니다. 비공식 플러그인을 참고하세요. 문서 페이지 자동 생성, 사용자 정의 스크립트 실행, 다른 서비스 통합 등의 기능을 추가하려면 목록을 확인하세요. 누군가 여러분을 위해 기능을 구현했을 수도 있습니다.

의욕이 넘친다면 플러그인 가이드나 플러그인 메소드 참조에서 직접 플러그인을 만드는 방법을 살펴보세요.

플러그인 설치하기

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

npm

npm install --save docusaurus-plugin-name

Yarn

yarn add docusaurus-plugin-name

pnpm

pnpm add docusaurus-plugin-name

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

docusaurus.config.js

export default {
  // ...
  plugins: ['@docusaurus/plugin-content-pages'],
};

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

docusaurus.config.js

export default {
  // ...
  plugins: ['./src/plugins/docusaurus-local-plugin'],
};

경로는 구성 파일에 절대적이거나 상대적이어야 합니다.

플러그인 설정하기

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

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

docusaurus.config.js

export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-xxx',
      {
        /* 옵션 */
      },
    ],
  ],
};

예:

docusaurus.config.js

export default {
  plugins: [
    // Basic usage.
    '@docusaurus/plugin-debug',

    // 옵션 오브젝트 사용(babel 스타일)
    [
      '@docusaurus/plugin-sitemap',
      {
        changefreq: 'weekly',
      },
    ],
  ],
};

멀티 인스턴스 플러그인과 플러그인 ID

모든 도큐사우루스 콘텐츠 플러그인은 멀티 플러그인 인스턴스를 지원합니다. 예를 들어 여러 문서 플러그인 인스턴스 또는 여러 블로그를 가지고 있는 경우 유용합니다. 플러그인 인스턴스마다 고유한 ID를 부여해야 하며 기본적으로 플러그인 ID는 default입니다.

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // other options
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // other options
      },
    ],
  ],
};

참고

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

테마 사용하기

테마는 플러그인과 똑같은 방식으로 로드됩니다. 사용자 관점에서 플러그인을 설치하고 구성할 때 themes와 plugins 항목을 서로 바꾸어 사용할 수 있습니다. The only nuance is that themes are loaded after plugins, and it's possible for a theme to override a plugin's default theme components.

팁

themes와 plugins 옵션은 서로 다른 단축 표기법으로 처리되므로 단축 표기법을 활용하려면 올바른 항목을 사용해야 합니다.

docusaurus.config.js

export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

프리셋 사용하기

프리셋(Preset)은 플러그인과 테마의 번들입니다. 예를 들어 구성 파일에서 @docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog 등을 순서대로 등록하고 설정하는 대신 @docusaurus/preset-classic 프리셋을 통해 한 곳에서 설정할 수 있습니다.

@docusaurus/preset-classic

기본 사전 설정은 create-docusaurus로 생성된 새로운 도큐사우루스 웹사이트에 기본적으로 제공됩니다. 다음 테마와 플러그인이 포함되어 있습니다.

• @docusaurus/theme-classic
• @docusaurus/theme-search-algolia
• @docusaurus/plugin-content-docs
• @docusaurus/plugin-content-blog
• @docusaurus/plugin-content-pages
• @docusaurus/plugin-debug
• @docusaurus/plugin-google-gtag
• @docusaurus/plugin-google-tag-manager
• @docusaurus/plugin-google-analytics (deprecated)
• @docusaurus/plugin-sitemap
• @docusaurus/plugin-svgr

classic 프리셋은 각 옵션 항목을 해당 플러그인/테마로 전달합니다.

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // Debug defaults to true in dev, false in prod
        debug: undefined,
        // Will be passed to @docusaurus/theme-classic.
        theme: {
          customCss: ['./src/css/custom.css'],
        },
        // Will be passed to @docusaurus/plugin-content-docs (false to disable)
        docs: {},
        // Will be passed to @docusaurus/plugin-content-blog (false to disable)
        blog: {},
        // Will be passed to @docusaurus/plugin-content-pages (false to disable)
        pages: {},
        // Will be passed to @docusaurus/plugin-sitemap (false to disable)
        sitemap: {},
        // Will be passed to @docusaurus/plugin-svgr (false to disable)
        svgr: {},
        // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
        gtag: {},
        // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified)
        googleTagManager: {},
        // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified)
        googleAnalytics: {},
      },
    ],
  ],
};

프리셋 설치하기

프리셋은 npm 패키지 형태로 제공됩니다. npm을 사용해 다른 npm 패키지처럼 설치할 수 있습니다.

npm

npm install --save @docusaurus/preset-classic

Yarn

yarn add @docusaurus/preset-classic

pnpm

pnpm add @docusaurus/preset-classic

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

docusaurus.config.js

export default {
  // ...
  presets: ['@docusaurus/preset-classic'],
};

프리셋 경로는 구성 파일에 상대적으로 설정할 수 있습니다.

docusaurus.config.js

export default {
  // ...
  presets: ['./src/presets/docusaurus-local-preset'],
};

프리셋 생성:

프리셋은 플러그인 생성자와 같은 형태의 함수입니다. 사이트 구성에서 허용되는 방식처럼 { plugins: PluginConfig[], themes: PluginConfig[] } 오브젝트를 반환해야 합니다. 예를 들어 다음과 같은 테마와 플러그인을 포함하는 프리셋을 설정할 수 있습니다.

src/presets/docusaurus-preset-multi-docs.js

export default function preset(context, opts = {}) {
  return {
    themes: [['docusaurus-theme-awesome', opts.theme]],
    plugins: [
      // Using three docs plugins at the same time!
      // Assigning a unique ID for each without asking the user to do it
      ['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
      ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
    ],
  };
}

그런 다음 도큐사우루스 설정에서 프리셋 항목을 지정해줍니다.

docusaurus.config.js

export default {
  presets: [
    [
      './src/presets/docusaurus-preset-multi-docs.js',
      {
        theme: {hello: 'world'},
        docs1: {path: '/docs'},
        docs2: {path: '/community'},
        docs3: {path: '/api'},
      },
    ],
  ],
};

위의 방법은 아래와 같이 설정한 것과 같습니다.

docusaurus.config.js

export default {
  themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
  plugins: [
    ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs2', path: '/community'}],
    ['@docusaurus/plugin-content-docs', {id: 'docs3', path: '/api'}],
  ],
};

프리셋은 특정 플러그인과 테마를 같이 사용하려고 할 때 유용한 기능입니다. 옵션과 함께 연결할 수 있습니다. 예를 들면 여러 플러그인에 하나의 옵션을 전달합니다.

모듈 단축 표기법

도큐사우루스는 플러그인, 테마, 프리셋에 대한 단축 표기법을 지원합니다. 플러그인/테마/프리셋 이름이 보여질 때 아래의 순서대로 로드를 시도합니다.

• [name] (예: content-docs)
• @docusaurus/[moduleType]-[name] (예: @docusaurus/plugin-content-docs)
• docusaurus-[moduleType]-[name] (예: docusaurus-plugin-content-docs)

moduleType은 모듈 이름이 선언된 필드에 따라 'preset', 'theme', 'plugin' 중 하나가 됩니다. 성공적으로 찾은 첫 번째 모듈 이름이 로드됩니다.

이름의 범위가 지정되어 있다면(@로 시작하는) 첫 번째 슬래시를 기준으로 범위와 패키지 이름이 나뉘어집니다.

@scope
^----^
 scope  (no name!)

@scope/awesome
^----^ ^-----^
 scope   name

@scope/awesome/main
^----^ ^----------^
 scope     name

이름(@jquery 같은)이 없다면 [scope]/docusaurus-[moduleType](예: @jquery/docusaurus-plugin)이 로드됩니다. 그렇지 않으면 다음 항목 로드를 시도합니다.

• [scope]/[name] (예: @jquery/content-docs)
• [scope]/docusaurus-[moduleType]-[name] (예: @jquery/docusaurus-plugin-content-docs)

다음은 plugins 필드에 등록된 플러그인에 대한 몇 가지 예입니다. 플러그인에 대한 일관성 있는 명명 규칙을 요구사하는 ESLint나 Babel과 다르게 도큐사우루스는 좀 더 자유로운 명명 방식을 허용하며 명확하지는 않지만 위에 정의된 우선 순위를 따릅니다.

선언	다음과 같이 처리됩니다
awesome	docusaurus-plugin-awesome
sitemap	@docusaurus/plugin-sitemap
@my-company	@my-company/docusaurus-plugin (가능한 유일한 해결책입니다!)
@my-company/awesome	@my-company/docusaurus-plugin-awesome
@my-company/awesome/web	@my-company/docusaurus-plugin-awesome/web