プラグインの利用

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. プラグインがインスールされていない場合、サイトにルートが含まれることはありません。

You may not need to install common plugins one-by-one though: they can be distributed as a bundle in a preset. ほとんどのユーザーにとって、プラグインはプリセット設定によって設定されます。

We maintain a list of official plugins, but the community has also created some unofficial plugins. 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.

プラグインのインストール

プラグインは通常npmパッケージの形態を取るため、npmを利用して他のnpmパッケージと同じようにインストールします。

npm
Yarn
pnpm
Bun

npm install --save docusaurus-plugin-name

yarn add docusaurus-plugin-name

pnpm add docusaurus-plugin-name

bun add docusaurus-plugin-name

Then you add it in your site's docusaurus.config.js's plugins option:

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

次のようにすれば、Docusaurusはローカルディレクトリからプラグインを読み込むこともできます。

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

パスは絶対パスまたは設定ファイルからの相対パスでなければなりません。

Configuring plugins

プラグインの最も基本的な用法としては、プラグイン名またはプラグインへのパスを与えるだけです。

ただし、プラグインは、設定内で名前及びオプションオブジェクトを2つの要素からなるタプルにすることで、オプションを指定することができます。この書き方は通常「Babelスタイル」と呼ばれます。

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

例：

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

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

複数インスタンスのプラグインとプラグインID

全てのDocusaurusコンテンツプラグインは、複数のプラグインインスタンスに対応することができます。 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
export default {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-1',
        // その他のオプション
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-2',
        // その他のオプション
      },
    ],
  ],
};

メモ

At most one plugin instance can be the "default plugin instance", by omitting the id attribute, or using id: 'default'.

テーマの使用

テーマはプラグインと全く同じ方法で読み込まれます。 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.

ヒント

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
export default {
  // ...
  themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
};

プリセットの使用

プリセットとは、プラグインやテーマをひとまとめにしたものです。 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. これには以下のテーマ及びプラグインが含まれています。

標準（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
Yarn
pnpm
Bun

npm install --save @docusaurus/preset-classic

yarn add @docusaurus/preset-classic

pnpm add @docusaurus/preset-classic

bun add @docusaurus/preset-classic

Then, add it in your site's docusaurus.config.js's presets option:

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

プリセットパスは、以下のように設定ファイルからの相対パスにすることができます。

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

プリセットの作成

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
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の設定内で、プリセットを次のように設定します。

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

This is equivalent to doing:

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

This is especially useful when some plugins and themes are intended to be used together. You can even link their options together, e.g. pass one option to multiple plugins.

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] (like content-docs)
@docusaurus/[moduleType]-[name] (like @docusaurus/plugin-content-docs)
docusaurus-[moduleType]-[name] (like docusaurus-plugin-content-docs)

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 there is no name (like @jquery), [scope]/docusaurus-[moduleType] (i.e. @jquery/docusaurus-plugin) is loaded. Otherwise, the following are attempted:

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

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.

宣言	次のように解決される場合あり
`awesome`	`docusaurus-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`

プラグインのインストール​

Configuring plugins​

複数インスタンスのプラグインとプラグインID​

テーマの使用​

プリセットの使用​

@docusaurus/preset-classic​

プリセットのインストール​

プリセットの作成​

Module shorthands​