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

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
const path = require('path');

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

플러그인 설정하기

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

However, plugins can have options specified by wrapping the name and an options object in a two-member tuple inside your config. This style is usually called "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

모든 도큐사우루스 콘텐츠 플러그인은 멀티 플러그인 인스턴스를 지원합니다. For example, it may be useful to have multiple docs plugin instances or multiple blogs. It is required to assign a unique id to each plugin instance, and by default, the plugin id is 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—the line between them is blurry. From the consumer perspective, the themes and plugins entries are interchangeable when installing and configuring a plugin. 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

The themes and plugins options lead to different shorthand resolutions, so if you want to take advantage of shorthands, be sure to use the right entry!

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

프리셋 사용하기

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'],
};

로컬 디렉터리에서 프리셋을 불러오기 위해서는 아래와 같이 설정해주어야 합니다.

docusaurus.config.js
const path = require('path');

module.exports = {
// ...
presets: [path.resolve(__dirname, '/path/to/docusaurus-local-preset')],
};

프리셋은 여러분의 도큐사우루스 설정에 플러그인과 테마를 한 번에 추가할 수 있는 도구라고 할 수 있습니다. For example, you can specify a preset that includes the following themes and plugins:

/path/to/docusaurus-local-preset
module.exports = 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
module.exports = {
presets: [
[
path.resolve(__dirname, '/path/to/docusaurus-local-preset'),
{
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'}],
],
};

프리셋은 특정 플러그인과 테마를 같이 사용하려고 할 때 유용한 기능입니다. You can even link their options together, e.g. pass one option to multiple plugins.

@docusaurus/preset-classic

The classic preset is shipped by default to new Docusaurus website created with create-docusaurus. 아래 목록에 있는 플러그인과 테마 묶음입니다.

테마플러그인
@docusaurus/theme-classic@docusaurus/plugin-content-docs
@docusaurus/theme-search-algolia@docusaurus/plugin-content-blog
@docusaurus/plugin-content-pages
@docusaurus/plugin-debug
@docusaurus/plugin-google-analytics
@docusaurus/plugin-google-gtag
@docusaurus/plugin-sitemap

플러그인 옵션을 개별적으로 지정하고 싶다면 특정 플러그인에서 필요한 필드를 전달할 수 있습니다. 예를 들어 @docusaurus/theme-classic에서 customCss 항목을 프리셋 필드에 전달합니다.

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: {},
},
},
],
],
};

Module shorthands

Docusaurus supports shorthands for plugins, themes, and presets. When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:

  • [name]
  • @docusaurus/[moduleType]-[name]
  • docusaurus-[moduleType]-[name],

where moduleType is one of 'preset', 'theme', 'plugin', depending on which field the module name is declared in. The first module name that's successfully found is loaded.

If the name is scoped (beginning with @), the name is first split into scope and package name by the first slash:

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

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

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

If the name is not specified, {scope}/docusaurus-{type} is loaded. Otherwise, the following are attempted:

  • [scope]/[name]
  • [scope]/docusaurus-[moduleType]-[name]

Below are some examples, for a plugin registered in the plugins field. Note that unlike ESLint or Babel where a consistent naming convention for plugins is mandated, Docusaurus permits greater naming freedom, so the resolutions are not certain, but follows the priority defined above.

DeclarationMay be resolved as
awesomedocusaurus-plugin-awesome
sitemap@docusaurus/plugin-sitemap
@my-company@my-company/docusaurus-plugin (the only possible resolution!)
@my-company/awesome@my-company/docusaurus-plugin-awesome
@my-company/awesome/web@my-company/docusaurus-plugin-awesome/web