Skip to main content

index

Docusaurusは、シンプルで使いやすいドキュメンテーションフレームワークとして知られている。デフォルトでは、src/css/custom.cssファイルを使用してグローバルなCSSスタイルを定義できるが、サイトのデザインをより細かくコントロールしたい場合、docsとblogで異なるCSSを適用することが効果的である。

なぜdocsとblogで異なるCSSを適用するのか​

docsとblogはそれぞれ異なる目的と特性を持っているため、適用するCSSも別々に設定することが望ましい。

docsは、ソフトウェアやサービスの使い方、APIリファレンス、チュートリアルなどの技術文書を提供することを目的としている。そのため、docsでは以下のような点を重視してCSSを設定する必要がある。

  • 読みやすさ：コンテンツが読みやすいように、適切なフォントサイズ、行間、段落間隔などを設定する。
  • シンプルさ：装飾的な要素を最小限に抑え、コンテンツに集中できるようにする。
  • ナビゲーションのしやすさ：サイドバーやテーブルオブコンテンツを適切に配置し、ユーザーが目的のコンテンツに素早くアクセスできるようにする。

一方、blogは、社員やコミュニティメンバーの知見やオピニオンを共有したり、会社やプロダクトに関する最新情報を発信したりすることを目的としている。そのため、blogでは以下のような点を重視してCSSを設定することが効果的である。

  • ブランディング：会社やプロダクトのブランドイメージに合わせたデザインを適用し、ブログが企業の顔としての役割を果たせるようにする。
  • 視覚的な訴求力：アイキャッチ画像や図版を効果的に使用し、読者の興味を引き付ける。
  • SNSシェアボタンの配置：記事をSNSでシェアしやすいように、シェアボタンを目立つ位置に配置する。

このように、docsとblogではコンテンツの性質や目的が異なるため、適用するCSSもそれぞれの特性に合わせて最適化することが重要である。Docusaurusでdocsとblogに異なるCSSを適用できる機能は、サイト全体の一貫性を保ちつつ、各セクションの個性を表現するのに役立つ。

また、docsとblogに適用するCSSを分離することで、メンテナンス性も向上する。一方のセクションのデザインを変更する際に、もう一方のセクションに意図しない影響を与えるリスクを軽減できる。

以上のような理由から、Docusaurusでdocsとblogに異なるCSSを適用することは、サイトのデザインと機能性を向上させるために有効な方法だと言える。

Docusaurusのコンポーネントをオーバーライドする方法​

Docusaurusでは、デフォルトのコンポーネントをオーバーライドすることで、サイトのデザインや機能をカスタマイズできる。オーバーライドは、Docusaurusが提供するデフォルトのコンポーネントを独自のコンポーネントで置き換える仕組みである。

オーバーライドは、以下の手順で行う。

  1. src/themeディレクトリに、オーバーライドするコンポーネントと同じ名前のディレクトリを作成する。
  2. そのディレクトリ内に、デフォルトのコンポーネントと同じ名前のファイルを作成する。
  3. ファイル内で、デフォルトのコンポーネントをインポートし、独自のコンポーネントをエクスポートする。

例えば、DocItemコンポーネントをオーバーライドする場合は、以下のように実装する。

src/theme/DocItem/index.js
import React from 'react';
import DocItem from '@theme-original/DocItem';
import './docs.css';

export default function DocItemWrapper(props) {
  return (
    <>
      <DocItem {...props} />
    </>
  );
}

この例では、@theme-original/DocItemからデフォルトのDocItemコンポーネントをインポートし、DocItemWrapperという新しいコンポーネントを定義している。DocItemWrapperは、デフォルトのDocItemコンポーネントをラップし、独自のCSSファイル（docs.css）を適用している。

オーバーライドするコンポーネントは、@theme-originalのプレフィックスを付けてインポートする必要がある。これにより、Docusaurusはデフォルトのコンポーネントと区別し、オーバーライドされたコンポーネントを使用する。

オーバーライドは、BlogPostItemやBlogListPageなどの他のコンポーネントでも同様に実装できる。

オーバーライドを使用することで、Docusaurusのデフォルトのデザインや機能を維持しつつ、サイトの要件に合わせて特定の部分をカスタマイズできる。これにより、開発者はDocusaurusの利便性を享受しながら、独自のデザインや機能を実装できる。

ただし、オーバーライドを行う際は、Docusaurusのアップデートによって変更が上書きされる可能性があることに注意が必要である。オーバーライドしたコンポーネントは、Docusaurusのバージョンアップの際に、変更内容を確認し、必要に応じて修正する必要がある。

docs内のマークダウンにCSSを適用する手順​

docs内のマークダウンにのみ特定のCSSを適用する方法は以下の通りである。

1. DocItemのオーバーライド​

src/theme/DocItem/index.jsファイルを作成し、以下のコードを記述する。このファイルは、DocusaurusのデフォルトのDocItemコンポーネントをオーバーライドするためのものである。

src/theme/DocItem/index.js
import React from 'react';
import DocItem from '@theme-original/DocItem';
import './docs.css';

export default function DocItemWrapper(props) {
  return (
    <>
      <DocItem {...props} />
    </>
  );
}

2. CSSファイルの作成​

次に、src/theme/DocItem/docs.cssファイルを作成し、docs内のマークダウンに適用したいCSSを記述する。ここでは、h2要素のスタイルを変更する例を示す。

src/theme/DocItem/docs.css
.markdown > h2 {
  font-size: 1.75rem;
  line-height: 1;
  padding: 0.5em 0.4em;
  color: white;
  background-color: #58a9ef;
  border: dashed 1px #3a9aec;
  box-shadow: 0 0 0 5px #58a9ef;
}

3. 設定の反映​

最後に、docusaurus.config.jsファイルを開き、themeConfigにcustomCssを追加する。

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    customCss: [require.resolve('./src/theme/DocItem/docs.css')],
  },
};

これで、docs.cssファイルに記述したCSSが、docs内のマークダウンにのみ適用されるようになる。一方、src/css/custom.cssに記述したCSSは、サイト全体に適用される。

blog内のマークダウンにCSSを適用する手順​

blog内のマークダウンにCSSを適用する方法は以下の通りである。

1. BlogPostItemのオーバーライド​

src/theme/BlogPostItem/index.jsファイルを作成し、以下のコードを記述する。このファイルは、DocusaurusのデフォルトのBlogPostItemコンポーネントをオーバーライドするためのものである。

src/theme/BlogPostItem/index.js
import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import './blog-post-item.css';

export default function BlogPostItemWrapper(props) {
  return (
    <>
      <BlogPostItem {...props} />
    </>
  );
}

2. CSSファイルの作成​

src/theme/BlogPostItem/blog-post-item.cssファイルを作成し、blog内のマークダウンに適用したいCSSを記述する。

src/theme/BlogPostItem/blog-post-item.css
/* ここにblog内のマークダウンに適用するCSSを記述 */

3. 設定の反映​

docusaurus.config.jsファイルを開き、themeConfigにcustomCssを追加する。

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    // ...
    customCss: [require.resolve('./src/theme/BlogPostItem/blog-post-item.css')],
  },
};

これで、blog-post-item.cssファイルに記述したCSSが、blog内のマークダウンにのみ適用されるようになる。

ブログ記事一覧ページにCSSを適用する方法​

ブログ記事一覧ページ（/blog）にもCSSを適用したい場合は、以下の手順を追加で実行する。

1. BlogListPageのオーバーライド​

src/theme/BlogListPage/index.jsファイルを作成し、以下のコードを記述する。

src/theme/BlogListPage/index.js
import React from 'react';
import BlogListPage from '@theme-original/BlogListPage';
import './blog-list-page.css';

export default function BlogListPageWrapper(props) {
  return (
    <>
      <BlogListPage {...props} />
    </>
  );
}

2. CSSファイルの作成​

src/theme/BlogListPage/blog-list-page.cssファイルを作成し、ブログ記事一覧ページに適用したいCSSを記述する。

src/theme/BlogListPage/blog-list-page.css
.blog-list-page header h2 {
  font-size: 2rem;
  margin-bottom: 2rem;
}

3. 設定の反映​

docusaurus.config.jsのcustomCssにblog-list-page.cssを追加する。

customCss: [
  require.resolve('./src/theme/BlogPostItem/blog-post-item.css'),
  require.resolve('./src/theme/BlogListPage/blog-list-page.css'),
],

これにより、ブログ記事の本文と一覧ページの両方に、それぞれ独自のCSSを適用することができる。

まとめ​

Docusaurusでdocsとblogにそれぞれ異なるCSSを適用する方法について解説した。この方法を活用することで、サイトのデザインをより細かくコントロールできる。

サイトのデザインは、コンテンツの見やすさや読みやすさに直結する重要な要素である。docsとblogそれぞれの目的や特性に合わせたCSSを適用することで、ユーザーエクスペリエンスの向上につなげることができる。