バージョン: 3.5.2

`docusaurus.config.js`

情報

例については、構成の「はじめに」を参照してください。

概要

docusaurus.config.js にはサイトの構成が含まれており、サイトのルートディレクトリに配置されます。

注記

TypeScript Docusaurusコードベースの場合、設定ファイルはdocusaurus.config.tsという名前になる場合があります。構文は、型が追加された点を除いて、js設定ファイルとほぼ同じです。例については、Docusaurus Webサイト自体を参照してください。

このファイルはNode.jsで実行され、サイト構成オブジェクト、またはそれを作成する関数をエクスポートする必要があります。

docusaurus.config.jsファイルは以下をサポートしています

例

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.dokyumento.jp',
  // your site config ...
};

docusaurus.config.js
export default async function createConfigAsync() {
  return {
    title: 'Docusaurus',
    url: 'https://docusaurus.dokyumento.jp',
    // your site config ...
  };
}

ヒント

より詳しい例と説明については、docusaurus.config.jsを宣言するための構文を参照してください。

必須フィールド

`title`

型: string

ウェブサイトのタイトル。メタデータとブラウザータブのタイトルとして使用されます。

docusaurus.config.js
export default {
  title: 'Docusaurus',
};

`url`

型: string

ウェブサイトのURL。これはトップレベルのホスト名と見なすこともできます。たとえば、https://facebook.github.io/metro/のURLはhttps://facebook.github.ioであり、https://docusaurus.dokyumento.jpのURLはhttps://docusaurus.dokyumento.jpです。このフィールドはbaseUrlフィールドに関連しています。

docusaurus.config.js
export default {
  url: 'https://docusaurus.dokyumento.jp',
};

`baseUrl`

型: string

サイトのベースURL。ホスト後のパスと見なすことができます。たとえば、https://facebook.github.io/metro/のベースURLは/metro/です。パスがないURLの場合、baseUrlは/に設定する必要があります。このフィールドはurlフィールドに関連しています。常に先頭と末尾にスラッシュがあります。

docusaurus.config.js
export default {
  baseUrl: '/',
};

オプションフィールド

`favicon`

型: string | undefined

サイトのfaviconへのパス。リンクのhrefで使用できるURLである必要があります。たとえば、faviconがstatic/img/favicon.icoにある場合

docusaurus.config.js
export default {
  favicon: '/img/favicon.ico',
};

`trailingSlash`

型: boolean | undefined

URL/リンクの末尾のスラッシュの有無、および静的なHTMLファイルの生成方法をカスタマイズできます

undefined (デフォルト): URLをそのままにし、/docs/myDoc.mdに対して/docs/myDoc/index.htmlを出力します
true: URL/リンクに末尾のスラッシュを追加し、/docs/myDoc.mdに対して/docs/myDoc/index.htmlを出力します
false: URL/リンクから末尾のスラッシュを削除し、/docs/myDoc.mdに対して/docs/myDoc.htmlを出力します

ヒント

静的ホスティングプロバイダーはそれぞれ異なる方法で静的ファイルを提供します（この動作は時間の経過とともに変化する可能性さえあります）。

適切な設定を選択するには、デプロイメントガイドとslorber/trailing-slash-guideを参照してください。

`i18n`

型: Object

サイトをローカライズするためのi18n構成オブジェクト。

例

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fa'],
    path: 'i18n',
    localeConfigs: {
      en: {
        label: 'English',
        direction: 'ltr',
        htmlLang: 'en-US',
        calendar: 'gregory',
        path: 'en',
      },
      fa: {
        label: 'فارسی',
        direction: 'rtl',
        htmlLang: 'fa-IR',
        calendar: 'persian',
        path: 'fa',
      },
    },
  },
};

defaultLocale: (1) ベースURLに名前がないロケール、(2) --localeオプションなしでdocusaurus startで起動するロケール、(3) <link hrefLang="x-default">タグに使用されるロケール
locales: サイトにデプロイされたロケールのリスト。defaultLocaleを含める必要があります。
path: すべてのロケールフォルダーが相対的に参照するルートフォルダー。絶対パスまたは構成ファイルに対する相対パスを使用できます。デフォルトはi18nです。
localeConfigs: 各ロケールに対する個々のオプション。
- label: ロケールドロップダウンに表示されるこのロケールのラベル。
- direction: ltr（デフォルト）またはrtl（ペルシア語、アラビア語、ヘブライ語などの右から左に読む言語の場合）。ロケールのCSSとHTMLメタ属性を選択するために使用されます。
- htmlLang: <html lang="...">（またはその他のDOMタグ名）と<link ... hreflang="...">で使用するBCP 47言語タグ
- calendar: 日付の時代を計算するために使用されるカレンダー。表示される実際の文字列を制御しないことに注意してください。MM/DD/YYYYとDD/MM/YYYYはどちらもgregoryです。形式（DD/MM/YYYYまたはMM/DD/YYYY）を選択するには、ロケール名をen-GBまたはen-USに設定します（enはen-USを意味します）。
- path: このロケールのすべてのプラグインローカライズフォルダーが相対的に参照するルートフォルダー。i18n.pathに対して解決されます。デフォルトはロケールの名前です。注：これはロケールのbaseUrlには影響しません。ベースURLのカスタマイズは開発中です。

`future`

型: Object

future構成オブジェクトを使用すると、まだ準備が整っていない、今後の/不安定な/実験的なDocusaurus機能を選択できます。

また、次のメジャーバージョンで発生する予定の破壊的な変更をオプトインして、前のバージョンを維持しながら、次のバージョンに向けてサイトを準備することもできます。Remix Future Flagsブログ記事で、この考え方が詳しく説明されています。

マイナーバージョンでの破壊的な変更

experimental_またはunstable_でプレフィックスが付いている機能は、セマンティックバージョニングの破壊的な変更とは見なされず、マイナーバージョンで変更される可能性があります。

v<MajorVersion>_ (v6_ v7_など) でプレフィックスが付いている機能は、次のメジャーバージョンでデフォルトでオンになることが予想されるfutureフラグです。これらの変更の可能性は低いですが、そうする可能性は残されています。

future APIの破壊的な変更は簡単に対処する必要があり、マイナー/メジャーバージョンのブログ記事で文書化されます。

例

docusaurus.config.js
export default {
  future: {
    experimental_storage: {
      type: 'localStorage',
      namespace: true,
    },
    experimental_router: 'hash',
  },
};

experimental_storage: テーマの作成者が尊重するように努める必要がある、サイト全体のブラウザーストレージオプション。
- type: テーマの作成者が使用する必要があるブラウザーストレージ。使用可能な値は、localStorageとsessionStorageです。デフォルトはlocalStorageです。
- namespace: Docusaurusサイトが同じドメインまたはlocalhostでホストされている場合に、ストレージキーの競合を避けるために、ブラウザーストレージキーに名前空間を付けるかどうか。使用可能な値はstring | booleanです。名前空間はストレージキーの末尾 (key-namespace) に付加されます。サイトのurl + baseUrlからランダムな名前空間を自動生成するには、trueを使用します。デフォルトはfalseです（名前空間なし、過去の動作）。
experimental_router: 使用するルーターのタイプ。使用可能な値はbrowserとhashです。デフォルトはbrowserです。hashルーターは、静的サイトの生成をオプトアウトし、単一のindex.htmlエントリポイントファイルを持つ完全にクライアント側のアプリを作成する場合など、まれな場合にのみ役立ちます。これは、Webサーバーを実行せずにローカルで参照できる.zipアーカイブとしてDocusaurusサイトを配布するのに役立ちます。

`noIndex`

型: boolean

このオプションは、検索エンジンにサイトのインデックス作成を避けるように指示するために、すべてのページに<meta name="robots" content="noindex, nofollow">を追加します（詳細についてはこちらを参照してください）。

例

docusaurus.config.js
export default {
  noIndex: true, // Defaults to `false`
};

`onBrokenLinks`

型: 'ignore' | 'log' | 'warn' | 'throw'

Docusaurusが壊れたリンクを検出した場合の動作。

デフォルトでは、エラーがスローされ、壊れたリンクが決して出荷されないようにします。

注記

壊れたリンクの検出は、本番ビルド（docusaurus build）でのみ使用できます。

`onBrokenAnchors`

型: 'ignore' | 'log' | 'warn' | 'throw'

DocusaurusがDocusaurusのHeadingコンポーネントで宣言された壊れたアンカーを検出した場合の動作。

デフォルトでは、壊れたアンカーについて知らせるために警告が表示されます。

`onBrokenMarkdownLinks`

型: 'ignore' | 'log' | 'warn' | 'throw'

Docusaurusが壊れたMarkdownリンクを検出したときの動作。

デフォルトでは、壊れたMarkdownリンクについて知らせるために警告が表示されます。

`onDuplicateRoutes`

型: 'ignore' | 'log' | 'warn' | 'throw'

Docusaurusが重複するルートを検出したときの動作。

デフォルトでは、yarn startまたはyarn buildを実行した後に警告が表示されます。

`tagline`

型: string

ウェブサイトのキャッチフレーズ。

docusaurus.config.js
export default {
  tagline:
    'Docusaurus makes it easy to maintain Open Source documentation websites.',
};

`organizationName`

型: string

リポジトリを所有するGitHubのユーザーまたは組織。docusaurus deployコマンドを使用しない場合は不要です。

docusaurus.config.js
export default {
  // Docusaurus' organization is facebook
  organizationName: 'facebook',
};

`projectName`

型: string

GitHubリポジトリの名前。docusaurus deployコマンドを使用しない場合は不要です。

docusaurus.config.js
export default {
  projectName: 'docusaurus',
};

`deploymentBranch`

型: string

静的ファイルをデプロイするブランチの名前。docusaurus deployコマンドを使用しない場合は不要です。

docusaurus.config.js
export default {
  deploymentBranch: 'gh-pages',
};

`githubHost`

型: string

サーバーのホスト名。GitHub Enterpriseを使用している場合に便利です。docusaurus deployコマンドを使用しない場合は不要です。

docusaurus.config.js
export default {
  githubHost: 'github.com',
};

`githubPort`

型: string

サーバーのポート。GitHub Enterpriseを使用している場合に便利です。docusaurus deployコマンドを使用しない場合は不要です。

docusaurus.config.js
export default {
  githubPort: '22',
};

`themeConfig`

型: Object

ナビゲーションバーやフッターなどのサイトUIをカスタマイズするためのテーマ設定オブジェクト。

例

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        width: 32,
        height: 32,
      },
      items: [
        {
          to: 'docs/docusaurus.config.js',
          activeBasePath: 'docs',
          label: 'docusaurus.config.js',
          position: 'left',
        },
        // ... other links
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Docs',
              to: 'docs/doc1',
            },
          ],
        },
        // ... other links
      ],
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here
    },
  },
};

`plugins`

型: PluginConfig[]

type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];

PluginModuleの形状については、プラグインメソッドのリファレンスを参照してください。

docusaurus.config.js
export default {
  plugins: [
    'docusaurus-plugin-awesome',
    ['docusuarus-plugin-confetti', {fancy: false}],
    () => ({
      postBuild() {
        console.log('Build finished');
      },
    }),
  ],
};

`themes`

型: PluginConfig[]

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

`presets`

型: PresetConfig[]

type PresetConfig = string | [string, any];

docusaurus.config.js
export default {
  presets: [],
};

`markdown`

グローバルなDocusaurus Markdownの設定。

型: MarkdownConfig

type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

type MDX1CompatOptions =
  | boolean
  | {
      comments: boolean;
      admonitions: boolean;
      headingIds: boolean;
    };

export type ParseFrontMatter = (params: {
  filePath: string;
  fileContent: string;
  defaultParseFrontMatter: ParseFrontMatter;
}) => Promise<{
  frontMatter: {[key: string]: unknown};
  content: string;
}>;

type MarkdownAnchorsConfig = {
  maintainCase: boolean;
};

type MarkdownConfig = {
  format: 'mdx' | 'md' | 'detect';
  mermaid: boolean;
  preprocessor?: MarkdownPreprocessor;
  parseFrontMatter?: ParseFrontMatter;
  mdx1Compat: MDX1CompatOptions;
  remarkRehypeOptions: object; // see https://github.com/remarkjs/remark-rehype#options
  anchors: MarkdownAnchorsConfig;
};

例

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    parseFrontMatter: async (params) => {
      const result = await params.defaultParseFrontMatter(params);
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
      return result;
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
    anchors: {
      maintainCase: true,
    },
  },
};

名前	型	デフォルト	説明
`format`	`'mdx' \| 'md' \| 'detect'`	`'mdx'`	Markdownコンテンツに使用するデフォルトのパーサー形式。'detect'を使用すると、ファイル拡張子（`.md`と`.mdx`）に基づいて適切な形式が自動的に選択されます。
`mermaid`	`boolean`	`false`	`true`の場合、Docusaurusは`mermaid`言語でMarkdownコードブロックをMermaid図としてレンダリングできます。
`preprocessor`	`MarkdownPreprocessor`	`undefined`	解析する前にMarkdownコンテンツ文字列を変更する機能を提供します。最後の手段や回避策として使用してください。通常、Remark/Rehypeプラグインを実装する方が優れています。
`parseFrontMatter`	`ParseFrontMatter`	`undefined`	独自のフロントマターパーサーを提供したり、デフォルトのパーサーを拡張したりする機能を提供します。詳細については、フロントマターガイドを参照してください。
`mdx1Compat`	`MDX1CompatOptions`	`{comments: true, admonitions: true, headingIds: true}`	Docusaurus v3+へのアップグレードを容易にするための互換性オプション。
`anchors`	`MarkdownAnchorsConfig`	`{maintainCase: false}`	Markdown見出しから生成されるアンカーの動作を制御するオプション
`remarkRehypeOptions`	`object`	`undefined`	カスタムの`remark-rehype`オプションを渡すことを可能にします。

`customFields`

Docusaurusは、不明なフィールドからdocusaurus.config.jsを保護します。カスタムフィールドを追加するには、customFieldsで定義してください。

型: Object

docusaurus.config.js
export default {
  customFields: {
    admin: 'endi',
    superman: 'lol',
  },
};

設定に不明なフィールドを追加しようとすると、ビルド時にエラーが発生します。

Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js

`staticDirectories`

サイトのディレクトリからの相対パスまたは絶対パスの配列。これらのパスの下のファイルは、そのままビルド出力にコピーされます。

型: string[]

例

docusaurus.config.js
export default {
  staticDirectories: ['static'],
};

`headTags`

HTMLの<head>に挿入されるタグの配列。値は、tagNameとattributesの2つのプロパティを含むオブジェクトである必要があります。tagNameは、作成されるタグを決定する文字列である必要があります（例："link"）。attributesは、属性と値のマップである必要があります。

型: { tagName: string; attributes: Object; }[]

例

docusaurus.config.js
export default {
  headTags: [
    {
      tagName: 'link',
      attributes: {
        rel: 'icon',
        href: '/img/docusaurus.png',
      },
    },
  ],
};

これにより、生成されたHTMLで<link rel="icon" href="img/docusaurus.png" />になります。

`scripts`

ロードするスクリプトの配列。値は、文字列または属性と値のマップのプレーンオブジェクトのいずれかです。<script>タグは、HTMLの<head>に挿入されます。プレーンオブジェクトを使用する場合、必須の属性はsrcのみであり、他の属性（それぞれがブール値または文字列値を持つ必要があります）も許可されます。

ここで追加された<script>はレンダリングをブロックすることに注意してください。そのため、オブジェクトにasync: true/defer: trueを追加することをお勧めします。

型: (string | Object)[]

例

docusaurus.config.js
export default {
  scripts: [
    // String format.
    'https://docusaurus.dokyumento.jp/script.js',
    // Object format.
    {
      src: 'https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js',
      async: true,
    },
  ],
};

`stylesheets`

ロードするCSSソースの配列。値は、文字列または属性と値のマップのプレーンオブジェクトのいずれかです。<link>タグは、HTMLの<head>に挿入されます。オブジェクトを使用する場合、必須の属性はhrefのみであり、他の属性（それぞれがブール値または文字列値を持つ必要があります）も許可されます。

型: (string | Object)[]

例

docusaurus.config.js
export default {
  stylesheets: [
    // String format.
    'https://docusaurus.dokyumento.jp/style.css',
    // Object format.
    {
      href: 'http://mydomain.com/style.css',
    },
  ],
};

情報

デフォルトでは、<link>タグにはrel="stylesheet"がありますが、カスタムのrel値を明示的に追加して、必ずしもスタイルシートである必要のない、任意の種類の<link>タグを挿入できます。

`clientModules`

サイト全体でグローバルにロードするクライアントモジュールの配列。

例

docusaurus.config.js
export default {
  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
};

`ssrTemplate`

アプリケーションのレンダリングに使用される、Etaの構文で記述されたHTMLテンプレート。これは、bodyタグにカスタム属性を設定したり、追加のmetaタグを追加したり、viewportをカスタマイズしたりするために使用できます。Docusaurusは、正しく機能するためにテンプレートが適切に構造化されていることに依存します。カスタマイズした後、テンプレートがアップストリームからの要件に準拠していることを確認する必要があります。

型: string

例

docusaurus.config.js
export default {
  ssrTemplate: `<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <%~ it.headTags %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="<%= it.baseUrl %><%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <link rel="preload" href="<%= it.baseUrl %><%= script %>" as="script">
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus">
      <%~ it.appHtml %>
    </div>
    <% it.scripts.forEach((script) => { %>
      <script src="<%= it.baseUrl %><%= script %>"></script>
    <% }); %>
    <%~ it.postBodyTags %>
  </body>
</html>`,
};

`titleDelimiter`

型: string

生成された<title>タグのタイトルの区切り文字として使用されます。

例

docusaurus.config.js
export default {
  titleDelimiter: '🦖', // Defaults to `|`
};

`baseUrlIssueBanner`

型: boolean

有効にすると、サイトがCSSまたはJavaScriptファイルをロードできない場合にバナーが表示されます。これは非常に一般的な問題であり、サイト設定のbaseUrlが間違っていることが原因であることがよくあります。

例

docusaurus.config.js
export default {
  baseUrlIssueBanner: true, // Defaults to `true`
};

A sample base URL issue banner. The style is very raw since the stylesheets failed to load. The text says "Your Docusaurus site did not load properly... Current configured baseUrl = / (default value); We suggest trying baseUrl = /build/

警告

このバナーは、間違ったベースURLが原因でアセットのロードに失敗した場合に備えて、インラインCSS/JSを必要とします。

厳格なコンテンツセキュリティポリシーがある場合は、無効にする必要があります。

概要​

必須フィールド​

title​

url​

baseUrl​

オプションフィールド​

favicon​

trailingSlash​

i18n​

future​

noIndex​

onBrokenLinks​

onBrokenAnchors​

onBrokenMarkdownLinks​

onDuplicateRoutes​

tagline​

organizationName​

projectName​

deploymentBranch​

githubHost​

githubPort​

themeConfig​

plugins​

themes​

presets​

markdown​

customFields​

staticDirectories​

headTags​

scripts​

stylesheets​

clientModules​

ssrTemplate​

titleDelimiter​

baseUrlIssueBanner​

概要