メインコンテンツへスキップ
バージョン: 3.5.2

テーマ設定

この設定は、すべてのメインテーマに適用されます。

共通事項​

カラーモード（ダークモード）​

クラシックテーマは、デフォルトでライトモードとダークモードをサポートしており、ユーザーはナビゲーションバーのスイッチで切り替えることができます。

colorModeオブジェクト内でカラーモードのサポートをカスタマイズできます。

有効なフィールド

名前型デフォルト値説明
defaultMode'light' | 'dark''light'ユーザーがサイトに初めてアクセスした際のカラーモード。
disableSwitchbooleanfalseナビゲーションバーのスイッチを非表示にします。単一のカラーモードをサポートする場合に便利です。
respectPrefersColorSchemebooleanfalseハードコーディングされたdefaultModeの代わりに、ユーザーのシステム設定を使用するprefers-color-schemeメディアクエリを使用するかどうか。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
警告

respectPrefersColorScheme: trueの場合、defaultModeはユーザーのシステム設定によって上書きされます。

単一のカラーモードのみをサポートする場合は、ユーザーのシステム設定を無視する方が良いでしょう。

メタ画像​

メタタグ、特にog:imageとtwitter:imageに使用されるデフォルト画像を設定できます。

有効なフィールド

名前型デフォルト値説明
imagestringundefinedサイトのメタ画像URL。サイトの「static」ディレクトリからの相対パス。SVGは使用できません。外部URLも使用できます。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

メタデータ​

追加のHTMLメタデータを設定したり、既存のメタデータの上書きができます。

有効なフィールド

名前型デフォルト値説明
metadataMetadata[][]すべてのフィールドは、<meta />タグに直接渡されます。有効なフィールドには、id、name、property、content、itempropなどがあります。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

お知らせバー​

ウェブサイトでお知らせを表示したい場合があると思います。そのような場合のために、お知らせバーを追加できます。これは、ナビゲーションバーの上部に表示される、固定ではないオプションで閉じることができるパネルです。すべての設定はannouncementBarオブジェクトに含まれています。

有効なフィールド

名前型デフォルト値説明
idstring'announcement-bar'このメッセージを識別する任意の値。
contentstring''お知らせのテキストコンテンツ。HTMLが補間されます。
backgroundColorstring'#fff'バー全体の背景色。
textColorstring'#000'お知らせテキストの色。
isCloseablebooleantrue'×'ボタンでこのお知らせを閉じることができるかどうか。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

プラグイン​

当社のメインテーマは、Docusaurusコアコンテンツプラグインに追加のテーマ設定オプションを提供します。

ドキュメント​

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    docs: {
      versionPersistence: 'localStorage',
      sidebar: {
        hideable: false,
        autoCollapseCategories: false,
      },
    },
  },
};

ブログ​

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
  },
};

有効なフィールド

名前型デフォルト値説明

ロゴは静的フォルダに配置できます。ロゴURLはデフォルトでサイトのベースURLに設定されます。独自のロゴURLを指定することもできますが、外部リンクの場合は新しいタブで開きます。さらに、ロゴリンクのtarget属性の値を上書きできます。これは、メインウェブサイトのサブディレクトリにドキュメントウェブサイトをホストしている場合に役立ちます。その場合、メインウェブサイトへのロゴのリンクは新しいタブで開く必要がないでしょう。

ダークモードのサポートを改善するために、このモード用の別のロゴを設定することもできます。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo_dark.svg',
        href: 'https://docusaurus.dokyumento.jp/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

themeConfig.navbar.itemsを使用して、ナビゲーションバーにアイテムを追加できます。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          type: 'docsVersionDropdown',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/facebook/docusaurus',
          position: 'right',
          className: 'header-github-link',
          'aria-label': 'GitHub repository',
        },
      ],
    },
  },
};

アイテムは、typeフィールドに基づいて異なる動作をすることができます。以下のセクションでは、使用可能なすべての種類のナビゲーションバーアイテムについて説明します。

デフォルトでは、ナビゲーションバーアイテムは通常のリンク（内部または外部）です。

React Routerは自動的にアクティブリンクのスタイルをリンクに適用しますが、エッジケースではactiveBasePathを使用できます。1つのリンクを複数の異なるパスでアクティブにする必要がある場合（同じサイドバーの下に複数のドキュメントフォルダがある場合など）、activeBaseRegexを使用できます。activeBaseRegexはactiveBasePathよりも柔軟な代替手段であり、優先されます。Docusaurusはこれを正規表現に変換し、現在のURLに対してテストします。

アウトバウンド（外部）リンクには、自動的にtarget="_blank" rel="noopener noreferrer"属性が追加されます。

有効なフィールド

名前型デフォルト値説明
注意

上記のフィールドに加えて、HTMLリンクに適用できる他の任意の属性を指定できます。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://#',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

dropdownタイプのナビゲーションバーアイテムには、追加のitemsフィールドがあります。これは、ナビゲーションバーアイテムの内部配列です。

ナビゲーションバーのドロップダウンアイテムは、以下の「リンクのような」アイテムタイプのみを受け付けます。

ドロップダウンベースアイテムもクリック可能なリンクであることに注意してください。そのため、このアイテムはプレーンなナビゲーションバーリンクのプロップスのいずれかを受け取ることができます。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://#',
            },
            {
              type: 'doc',
              label: 'Social',
              docId: 'social',
            },
            // ... more items
          ],
        },
      ],
    },
  },
};

特定のドキュメントにリンクしたい場合、この特別なナビゲーションバーアイテムタイプは、指定されたdocIdのドキュメントへのリンクをレンダリングします。同じサイドバーのドキュメントを参照している限り、navbar__link--activeクラスが取得されます。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

特定のサイドバーの最初のドキュメントリンク（ドキュメントリンクまたは生成されたカテゴリインデックスのいずれか）に、ナビゲーションバーの項目をリンクできます。ドキュメントIDをハードコードする必要はありません。

有効なフィールド

名前型デフォルト値説明
ヒント

サイドバーが頻繁に更新され、順序が安定していない場合は、このナビゲーションバー項目タイプを使用します。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // The navbar item will be linking to this doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

バージョン管理されたドキュメントを使用する場合、この特別なナビゲーションバー項目タイプは、サイトで使用可能なすべてのバージョンを含むドロップダウンを表示します。

ユーザーは、ドキュメントIDがバージョン間で一定である限り、同じドキュメントにとどまったまま、あるバージョンから別のバージョンに切り替えることができます。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'All versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

バージョン管理されたドキュメントを使用する場合、この特別なナビゲーションバー項目タイプは、ドキュメントの現在アクティブ/参照されているバージョン（現在のURLによって異なります）にリンクし、最新バージョンにフォールバックします。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
      ],
    },
  },
};

i18n機能を使用する場合、この特別なナビゲーションバー項目タイプは、サイトで使用可能なすべてのロケールを含むドロップダウンを表示します。

ユーザーは、同じページにとどまったまま、あるロケールから別のロケールに切り替えることができます。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Help us translate',
            },
          ],
        },
      ],
    },
  },
};

検索を使用する場合、検索バーはナビゲーションバーの一番右側の要素になります。

ただし、この特別なナビゲーションバー項目タイプを使用すると、デフォルトの場所を変更できます。

名前型デフォルト値説明
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

このナビゲーションバー項目タイプを使用して、独自のHTMLマークアップをナビゲーションバー項目内に表示することもできます。

名前型デフォルト値説明
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
      ],
    },
  },
};

自動非表示のスティッキナビゲーションバー​

ユーザーがページをスクロールダウンし始めるとナビゲーションバーが自動的に非表示になり、ユーザーがスクロールアップすると再び表示される、この便利なUI機能を有効にできます。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

テーマの切り替え機能を無効にすることなく、静的なナビゲーションバーのスタイルを設定できます。選択したスタイルは、ユーザーが選択したテーマに関係なく常に適用されます。

現在、darkとprimary（--ifm-color-primary色に基づく）の2つのスタイルオプションがあります。Infimaのドキュメントでスタイルのプレビューを参照できます。

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock​

Docusaurusは、コードブロックの強調表示にPrism React Rendererを使用します。すべての設定はprismオブジェクトにあります。

有効なフィールド

名前型デフォルト値説明
themePrismThemepalenightライトテーマのコードブロックに使用するPrismテーマ。
darkThemePrismThemepalenightダークテーマのコードブロックに使用するPrismテーマ。
defaultLanguagestringundefined明示的な言語を宣言していないコードブロックに使用するデフォルトの言語です。
magicCommentsMagicCommentConfig[]下記参照マジックコメントのリストです。
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];

テーマ​

デフォルトでは、構文の強調表示テーマとしてPalenightを使用します。使用可能なテーマのリストからカスタムテーマを指定することもできます。サイトがダークモードの場合、異なる構文強調表示テーマを使用することもできます。

設定例

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};
注意

行強調表示Markdown構文を使用する場合は、ダークモード構文強調表示テーマに異なる強調表示背景色を指定する必要がある場合があります。ガイダンスに関するドキュメントを参照してください。

デフォルト言語​

開始の三重バッククォート（つまり、```）の後に言語が追加されていない場合、コードブロックのデフォルトの言語を設定できます。有効な言語名を渡す必要があります。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

themeConfig.footerを使用して、ロゴと著作権をフッターに追加できます。ロゴは静的フォルダに配置できます。ロゴURLは、ナビゲーションバーのロゴと同じ方法で機能します。

有効なフィールド

名前型デフォルト値説明

設定例

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      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()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

themeConfig.footer.linksを使用して、フッターにリンクを追加できます。フッターの設定には、**複数列フッター**と**シンプルなフッター**の2種類があります。

複数列フッターリンクには、titleと各列のFooterItemのリストがあります。

名前型デフォルト値説明

各FooterItemの許容フィールド

名前型デフォルト値説明

複数列構成の例

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Style Guide',
            to: 'docs/',
          },
          {
            label: 'Second Doc',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus',
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus',
          },
          {
            label: 'Twitter',
            href: 'https://twitter.com/docusaurus',
          },
          {
            html: `
                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

シンプルなフッターには、1行に表示されるFooterItemのリストがあります。

シンプルな構成の例

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'Twitter',
        href: 'https://twitter.com/docusaurus',
      },
      {
        html: `
            <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

目次​

themeConfig.tableOfContentsを使用して、デフォルトの目次を調整できます。

名前型デフォルト値説明
minHeadingLevelnumber2目次に表示される最小の見出しレベル。2〜6の間でなければならず、最大値以下である必要があります。
maxHeadingLevelnumber3目次に表示される最大の見出しレベル。2〜6の整数である必要があります。

設定例

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

フック​

useColorMode​

カラコンテキストにアクセスするためのReactフック。このコンテキストには、ライトモードとダークモードを設定するための関数と、現在使用されているモードを示すブール変数が含まれています。

使用例

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
注意

useColorModeを呼び出すコンポーネントは、Layoutコンポーネントの子でなければなりません。

function ExamplePage() {
  return (
    <Layout>
      <Example />
    </Layout>
  );
}

i18n​

まずi18nの紹介をお読みください。

翻訳ファイルの場所​

  • **ベースパス**: website/i18n/[locale]/docusaurus-theme-[themeName]
  • **複数インスタンスパス**: N/A
  • **JSONファイル**: docusaurus write-translationsで抽出されました。
  • **Markdownファイル**: N/A

ファイルシステム構造の例​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # translations for the theme
├── navbar.json
└── footer.json