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

Using Plugins

The Docusaurus core doesn't provide any feature of its own. All features are delegated to individual plugins: the docs feature provided by the docs plugin; the blog feature provided by the blog plugin; or individual pages provided by the pages plugin. If there are no plugins installed, the site won't contain any routes.

You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. For most users, plugins are configured through the preset configuration.

공식 지원 플러그인 목록에서 도큐사우루스에서 관리하는 플러그인을 확인할 수 있습니다. 하지만 일부 플러그인은 커뮤니티 내에서 만들어지기도 합니다. 비공식 플러그인을 참고하세요. If you want to add any feature: autogenerating doc pages, executing custom scripts, integrating other services... be sure to check out the list: someone may have implemented it for you!

If you are feeling energetic, you can also read the plugin guide or plugin method references for how to make a plugin yourself.

플러그인 설치하기

A plugin is usually an npm package, so you install them like other npm packages using npm.

npm install --save docusaurus-plugin-name

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

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

Docusaurus can also load plugins from your local directory, with something like the following:

docusaurus.config.js
module.exports = {
// ...
plugins: ['./src/plugins/docusaurus-local-plugin'],
};

Paths should be absolute or relative to the config file.

플러그인 설정하기

For the most basic usage of plugins, you can provide just the plugin name or the path to the plugin.

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

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

예:

docusaurus.config.js
module.exports = {
plugins: [
// Basic usage.
'@docusaurus/plugin-debug',

// With options object (babel style)
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
},
],
],
};

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

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

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

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

테마 사용하기

Themes are loaded in the exact same way as plugins. 사용자 관점에서 플러그인을 설치하고 구성할 때 themesplugins 항목을 서로 바꾸어 사용할 수 있습니다. 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.

tip

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

docusaurus.config.js
module.exports = {
// ...
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

프리셋 사용하기

Presets are bundles of plugins and themes. For example, instead of letting you register and configure @docusaurus/plugin-content-docs, @docusaurus/plugin-content-blog, etc. one after the other in the config file, we have @docusaurus/preset-classic preset allows you to configure them in one centralized place.

@docusaurus/preset-classic

The classic preset is shipped by default to new Docusaurus websites created with create-docusaurus. It contains the following themes and plugins:

The classic preset will relay each option entry to the respective plugin/theme.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
// 디버그 항목은 개발 시에는 true로 설정하고 배포 시에는 false로 설정합니다.
debug: undefined,
// 필드값을 @docusaurus/theme-classic로 전달합니다.
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
// 필드값을 @docusaurus/plugin-content-docs로 전달합니다(사용하지 않으면 false로 설정합니다)
docs: {},
// 필드값을 @docusaurus/plugin-content-blog로 전달합니다(사용하지 않으면 false로 설정합니다)
blog: {},
// 필드값을 @docusaurus/plugin-content-pages로 전달합니다(사용하지 않으면 false로 설정합니다)
pages: {},
// 필드값을 @docusaurus/plugin-content-sitemap로 전달합니다(사용하지 않으면 false로 설정합니다)
sitemap: {},
// 필드값을 @docusaurus/plugin-google-gtag로 전달합니다(명확하게 설정한 경우에만 사용할 수 있습니다)
gtag: {},
// 필드값을 @docusaurus/plugin-google-analytics로 전달합니다(명확하게 설정한 경우에만 사용할 수 있습니다)
googleAnalytics: {},
},
],
],
};

플러그인이나 테마 외에도 @docusaurus/theme-classicremark-admonitions@docusaurus/plugin-content-blog@docusaurus/plugin-content-docs에 remark 플러그인으로 추가할 수 있습니다.

admonitions 항목은 옵션으로 remark-admonitions에 전달됩니다. false 값을 설정하면 플러그인이 MDX에 추가되지 않습니다.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// oremark-admonitions 옵션
admonitions: {},
},
},
],
],
};

Installing presets

A preset is usually an npm package, so you install them like other npm packages using npm.

npm install --save @docusaurus/preset-classic

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

docusaurus.config.js
module.exports = {
// ...
presets: ['@docusaurus/preset-classic'],
};

Preset paths can be relative to the config file:

docusaurus.config.js
module.exports = {
// ...
presets: ['./src/presets/docusaurus-local-preset')],
};

Creating presets

A preset is a function with the same shape as the plugin constructor. It should return an object of { plugins: PluginConfig[], themes: PluginConfig[] }, in the same as how they are accepted in the site config. 예를 들어 다음과 같은 테마와 플러그인을 포함하는 프리셋을 설정할 수 있습니다.

src/presets/docusaurus-preset-multi-docs.js
module.exports = function preset(context, opts = {}) {
return {
themes: [['docusaurus-theme-awesome', opts.theme]],
plugins: [
// 3개의 문서 플러그인을 동시에 사용하기!
// 사용자에게 요청하지 않고 각각에 대한 고유한 ID 할당
['@docusaurus/plugin-content-docs', {...opts.docs1, id: 'docs1'}],
['@docusaurus/plugin-content-docs', {...opts.docs2, id: 'docs2'}],
['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
],
};
};

Then in your Docusaurus config, you may configure the preset:

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

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

docusaurus.config.js
module.exports = {
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'}],
],
};

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

모듈 단축 표기법

도큐사우루스는 플러그인, 테마, 프리셋에 대한 단축 표기법을 지원합니다. When it sees a plugin/theme/preset name, it tries to load one of the following, in that order:

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

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

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

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

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

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

If there is no name (like @jquery), [scope]/docusaurus-[moduleType] (i.e. @jquery/docusaurus-plugin) is loaded. 그렇지 않으면 다음 항목 로드를 시도합니다.

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

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

선언다음과 같이 처리됩니다
awesomedocusaurus-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