スタイルとレイアウト

ヒント

このセクションでは、スタイルシートを使用したスタイリングについて説明します。より高度なカスタマイズ（DOM構造、Reactコードなど）については、スウィズリングガイドを参照してください。

Docusaurusサイトは、シングルページのReactアプリケーションです。Reactアプリをスタイル設定する方法でスタイル設定できます。

いくつかのアプローチ/フレームワークがあり、あなたの好みや構築しようとしているウェブサイトの種類に応じて機能します。高度にインタラクティブでWebアプリのような動作をするウェブサイトは、スタイルをコンポーネントと共に配置する、より現代的なスタイリングアプローチから恩恵を受けます。コンポーネントのスタイリングは、コンポーネントをカスタマイズまたはスウィズリングする場合にも特に役立ちます。

グローバルスタイル

これは、ほとんどの開発者（フロントエンド開発者以外を含む）が慣れている、最も伝統的なスタイリング方法です。カスタマイズがあまりない小規模なウェブサイトでは問題ありません。

@docusaurus/preset-classicを使用している場合、独自のCSSファイル（例：/src/css/custom.css）を作成し、クラシックテーマのオプションとして渡すことでグローバルにインポートできます。

docusaurus.config.js

export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

そのファイル内で記述するCSSは、グローバルで使用可能になり、文字列リテラルを使用して直接参照できます。

/src/css/custom.css

.purple-text {
  color: rebeccapurple;
}

function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Purple Heading!</h1>
    </main>
  );
}

任意の要素にCSSを追加する場合は、ブラウザで開発者ツールを開いてクラス名を確認できます。クラス名はいくつかの種類があります。

• テーマクラス名。これらのクラス名は次のサブセクションに網羅的に記載されています。デフォルトのプロパティはありません。カスタムCSSでは、常にこれらの安定したクラス名をターゲットにすることを優先する必要があります。
• Infimaクラス名。これらのクラス名は、クラシックテーマに見られ、通常はblock__element--modifierのBEM規約に従います。通常は安定していますが、実装の詳細と見なされるため、一般的にターゲットにすることは避けるべきです。ただし、InfimaのCSS変数を変更できます。
• CSSモジュールクラス名。これらのクラス名は、本番環境ではハッシュが含まれ（codeBlockContainer_RIuc）、開発環境では長いファイルパスが付加されます。実装の詳細と見なされ、カスタムCSSでターゲットにすることはほとんど常に避けるべきです。どうしても必要な場合は、ハッシュを無視する属性セレクタ（[class*='codeBlockContainer']）を使用できます。

テーマクラス名

堅牢で保守可能なグローバルレイアウトスタイリングのために、いくつかの安定したCSSクラス名を用意しています。これらの名前はテーマに依存せず、カスタムCSSによってターゲットとなることを意図しています。

ヒント

堅牢なCSSセレクタを作成する方法が見つからない場合は、カスタマイズのユースケースを報告してください。新しいクラス名の追加を検討します。

安定したクラス名の網羅的なリスト

export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-page',
    blogAuthorsListPage: 'blog-authors-list-page',
    blogAuthorsPostsPage: 'blog-authors-posts-page',
    docsDocPage: 'docs-doc-page',
    docsTagsListPage: 'docs-tags-list-page',
    docsTagDocListPage: 'docs-tags-doc-list-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper',
    blogPages: 'blog-wrapper',
    docsPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
  common: {
    editThisPage: 'theme-edit-this-page',
    lastUpdated: 'theme-last-updated',
    backToTopButton: 'theme-back-to-top-button',
    codeBlock: 'theme-code-block',
    admonition: 'theme-admonition',
    unlistedBanner: 'theme-unlisted-banner',
    draftBanner: 'theme-draft-banner',
    admonitionType: (type: string) => `theme-admonition-${type}`,
  },
  layout: {
  },
  docs: {
    docVersionBanner: 'theme-doc-version-banner',
    docVersionBadge: 'theme-doc-version-badge',
    docBreadcrumbs: 'theme-doc-breadcrumbs',
    docMarkdown: 'theme-doc-markdown',
    docTocMobile: 'theme-doc-toc-mobile',
    docTocDesktop: 'theme-doc-toc-desktop',
    docFooter: 'theme-doc-footer',
    docFooterTagsRow: 'theme-doc-footer-tags-row',
    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
    docSidebarContainer: 'theme-doc-sidebar-container',
    docSidebarMenu: 'theme-doc-sidebar-menu',
    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
    docSidebarItemLink: 'theme-doc-sidebar-item-link',
    docSidebarItemCategoryLevel: (level: number) =>
      `theme-doc-sidebar-item-category-level-${level}` as const,
    docSidebarItemLinkLevel: (level: number) =>
      `theme-doc-sidebar-item-link-level-${level}` as const,
  },
  blog: {
    blogFooterTagsRow: 'theme-blog-footer-tags-row',
    blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row',
  },
  pages: {
    pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row',
  },
} as const;

Infimaを使用したサイトのスタイリング

@docusaurus/preset-classicは、基盤となるスタイリングフレームワークとしてInfimaを使用しています。Infimaは、コンテンツ中心のウェブサイト（ブログ、ドキュメント、ランディングページ）に適した柔軟なレイアウトと一般的なUIコンポーネントのスタイリングを提供します。詳細については、Infimaのウェブサイトをご覧ください。

create-docusaurusを使用してDocusaurusプロジェクトをスキャフォールディングすると、基本的なInfimaスタイルシートとデフォルトのスタイリングを使用してウェブサイトが生成されます。InfimaのCSS変数をグローバルに上書きできます。

/src/css/custom.css

:root {
  --ifm-color-primary: #25c2a0;
  --ifm-code-font-size: 95%;
}

Infimaは、各色について7つのシェードを使用します。選択した主要色のさまざまなシェードを見つけるには、ColorBoxを使用することをお勧めします。

または、次のツールを使用してウェブサイトのさまざまなシェードを生成し、変数を/src/css/custom.cssにコピーします。

ヒント

読みやすさを確保するために、主要色について少なくともWCAG-AAのコントラスト比を目指してください。Docusaurusウェブサイト自体を使用して、カラーパレットがどのように見えるかを確認してください。通常、1つの色はライトモードとダークモードの両方で機能しないため、ダークモードで代替パレットを使用できます。

主要色

背景

CSS変数名	16進数	調整	コントラスト評価
--ifm-color-primary-lightest	#3cad6e		不合格 🔴
--ifm-color-primary-lighter	#359962		不合格 🔴
--ifm-color-primary-light	#33925d		不合格 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

src/css/custom.css内の変数をこれらの新しい変数に置き換えます。

/src/css/custom.css

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

ダークモード

ライトモードでは、<html>要素にはdata-theme="light"属性があり、ダークモードではdata-theme="dark"です。したがって、特定の属性を持つhtmlをターゲットにすることで、CSSをダークモードのみに限定できます。

/* Overriding root Infima variables */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* Styling one class specially in dark mode */
[data-theme='dark'] .purple-text {
  color: plum;
}

ヒント

docusaurus-themeクエリ文字列パラメータから直接Docusaurusテーマを初期化できます。

例

/docs/?docusaurus-theme=dark

/docs/configuration?docusaurus-theme=light

データ属性

docusaurus-data-<key>パターンに従って、クエリ文字列パラメータを使用して<html>データ属性を挿入できます。これにより、クエリ文字列に基づいてページのスタイルを柔軟に変更できます。

たとえば、赤い枠線とナビゲーションバーのないページの1つをレンダリングしてみましょう。

/src/css/custom.css

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

iframeモード

iframeを介して別のサイトにいくつかのDocusaurusページを埋め込む予定がある場合、代替表示モードを作成し、https://mysite.com/docs/myDoc?docusaurus-data-mode=iframeなどのiframe URLを使用すると便利です。追加のスタイルを提供し、どのUI要素を維持または非表示にするかを決定するのは、あなたの責任です。

モバイルビュー

Docusaurusは、モバイル画面幅とデスクトップの区切りとして996pxを使用します。モバイルビューでレイアウトを異なるようにしたい場合は、メディアクエリを使用できます。

.banner {
  padding: 4rem;
}
/** In mobile view, reduce the padding */
@media screen and (max-width: 996px) {
  .heroBanner {
    padding: 2rem;
  }
}

ブレークポイントのカスタマイズ

ヘッダーやサイドバーなど、一部のReactコンポーネントは、モバイルビューの場合に異なるJavaScriptロジックを実装しています。カスタムCSSでブレークポイントの値を変更する場合は、swizzlingを使って使用されている`useWindowSize`フックの呼び出しも更新し、明示的なオプション引数を渡す必要があります。

CSSモジュール

CSSモジュールを使用してコンポーネントのスタイルを設定するには、スタイルシートファイルの名前に` .module.css`サフィックス（例：`welcome.module.css`）を付けます。WebpackはこれらのCSSファイルをCSSモジュールとして読み込み、クラス名はインポートされたCSSモジュールのプロパティとして参照する必要があります（プレーンな文字列を使用するのではなく）。これは、Create React Appで使用されている規則に似ています。

styles.module.css

.main {
  padding: 12px;
}

.heading {
  font-weight: bold;
}

.contents {
  color: #ccc;
}

import styles from './styles.module.css';

function MyComponent() {
  return (
    <main className={styles.main}>
      <h1 className={styles.heading}>Hello!</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

クラス名は、ビルド時にWebpackによってグローバルに一意なクラス名に変換されます。

CSS-in-JS

警告

CSS-in-JSのサポートは開発中であるため、MUIなどのライブラリに表示上の問題が発生する可能性があります。PR歓迎。

Sass/SCSS

Sass/SCSSをCSSプリプロセッサとして使用するには、非公式のDocusaurusプラグインdocusaurus-plugin-sassをインストールします。このプラグインは、グローバルスタイルとCSSモジュールのアプローチの両方で機能します。

1. docusaurus-plugin-sassをインストール

npm

npm install --save docusaurus-plugin-sass sass

Yarn

yarn add docusaurus-plugin-sass sass

pnpm

pnpm add docusaurus-plugin-sass sass

2. docusaurus.config.jsファイルにプラグインを含めます。

docusaurus.config.js

export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

3. 通常どおりSass/SCSSでスタイルシートを作成してインポートします。

Sass/SCSSを使用したグローバルスタイル

これで、@docusaurus/preset-classicのcustomCssプロパティをSass/SCSSファイルに設定できます。

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: ['./src/css/custom.scss'],
        },
        // ...
      },
    ],
  ],
};

Sass/SCSSを使用したモジュール

スタイルシートファイルの名前に` .module.scss`サフィックス（例：`welcome.module.scss`）を` .css`の代わりに使用します。Webpackは`sass-loader`を使用してスタイルシートをプリプロセスし、CSSモジュールとして読み込みます。

styles.module.scss

.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

TypeScriptサポート

Sass/SCSSモジュールでTypeScriptサポートを有効にするには、TypeScriptの設定を更新してdocusaurus-plugin-sassの型定義を追加する必要があります。これは、`tsconfig.json`ファイルで行うことができます。

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}