본문으로 건너뛰기
버전: 2.4.3

플러그인

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

Creating plugins

A plugin is a function that takes two parameters: context and options. 플러그인 인스턴스 오브젝트(또는 프로미스)를 반환합니다. 플러그인은 함수 또는 모듈로 만들 수 있습니다. For more information, refer to the plugin method references section.

Function definition

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

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

Module definition

별도 파일 또는 npm 패키지를 참조하는 모듈 경로로 플러그인을 사용할 수 있습니다.

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

Then in the folder my-plugin, you can create an index.js such as this:

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

You can view all plugins installed in your site using the debug plugin's metadata panel.

플러그인은 몇 가지 유형으로 제공됩니다.

  • package: an external package you installed
  • project: a plugin you created in your project, given to Docusaurus as a local file path
  • local: a plugin created using the function definition
  • synthetic: a "fake plugin" Docusaurus created internally, so we take advantage of our modular architecture and don't let the core do much special work. 구현 세부 사항이기 때문에 메타데이터에서 확인할 수 없습니다.

You can access them on the client side with useDocusaurusContext().siteMetadata.pluginVersions.

Plugin design

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

Theme design

When plugins have loaded their content, the data is made available to the client side through actions like createData + addRoute or setGlobalData. This data has to be serialized to plain strings, because plugins and themes run in different environments. Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through ReactDOM.render...

Themes provide the set of UI components to render the content. Most content plugins need to be paired with a theme in order to be actually useful. UI는 데이터 스키마와 별도의 레이어이므로 디자인을 쉽게 교체할 수 있습니다.

예를 들어 도큐사우루스 블로그는 블로그 플러그인과 블로그 테마로 구성이 되어 있습니다.

노트

This is a contrived example: in practice, @docusaurus/theme-classic provides the theme for docs, blog, and layouts.

docusaurus.config.js
module.exports = {
themes: ['theme-blog'],
plugins: ['plugin-content-blog'],
};

And if you want to use Bootstrap styling, you can swap out the theme with theme-blog-bootstrap (another fictitious non-existing theme):

docusaurus.config.js
module.exports = {
themes: ['theme-blog-bootstrap'],
plugins: ['plugin-content-blog'],
};

Now, although the theme receives the same data from the plugin, how the theme chooses to render the data as UI can be drastically different.

테마는 플러그인과 같은 lifecyelc 메소드를 공유합니다. 하지만 테마의 설계 목적에 따라 플러그인과 구현 방식은 달라질 수 있습니다.

테마는 여러분이 도큐사우루스 사이트를 빌드하고 사이트, 플러그인, 테마 자신이 사용할 수 있는 컴포넌트를 공급하도록 설계됩니다. A theme still acts like a plugin and exposes some lifecycle methods, but most likely they would not use loadContent, since they only receive data from plugins, but don't generate data themselves; themes are typically also accompanied by an src/theme directory full of components, which are made known to the core through the getThemePath lifecycle.

다시 정리하면

  • 테마는 플러그인과 같은 lifecycle 메소드를 공유합니다.
  • 테마는 모든 플러그인이 설정된 이후 동작합니다.
  • Themes add component aliases by providing getThemePath.