Docusaurus favicon 設定ガイド

Docusaurus の favicon を差し替えた後もフレームワークのデフォルトアイコンが表示される場合、ファイルが誤ったフォルダにあるか、設定がアイコンを参照していない可能性があります。アイコンを static/ に配置し、設定を1つ追加して、ビルド結果を検証してください。

前提条件

Docusaurus プロジェクト、正方形のソース画像、および docusaurus.config.ts へのアクセス権が必要です。

16×16 ピクセルでもマークが判別できる PNG または SVG。
プロジェクトの依存関係をインストールし、リポジトリのルートでターミナルを開いていること。

5ステップで Docusaurus favicon を追加する

適切なファイルを生成する。 Mzu favicondl で正方形の PNG または SVG を ICO に変換し、その後 SVG または PNG をダウンロードします。元のグラフィックは簡潔に保ち、wordmark 全体はタブ内で判読できません。
static/ ディレクトリを使う。 Docusaurus は、内部のパスを変更せずにこのディレクトリをビルド出力へコピーします。デフォルトアイコンを置き換えるか、ファイルを次のように配置します。
```
static/
└── img/
    ├── favicon.ico
    ├── favicon.svg
    └── favicon-32.png
```
組み込みの設定オプションを使用する。 docusaurus.config.ts 内の既存の設定オブジェクトに、次の設定を追加または維持します。
```
const config: Config = {
  // ...other options
  favicon: 'img/favicon.ico',
};
```
static/ からの相対パスを使い、先頭のスラッシュは付けません。組み込みオプションは icon link を追加して baseUrl を適用するため、ドメインのルートでもサブディレクトリ配下でも設定が機能します。
スケーラブルなアイコンとして SVG を追加する。 同じ設定オブジェクトに次のプロパティを追加し、ICO fallback は維持します。
```
headTags: [
  {
    tagName: 'link',
    attributes: {
      rel: 'icon',
      type: 'image/svg+xml',
      href: '/img/favicon.svg',
    },
  },
],
```
このタグは HTML の rel='icon' link relationshipに従います。headTags では値がリテラルとして扱われるため、base path を含める必要があります。baseUrl: '/docs/' の場合は /docs/img/favicon.svg を使用してください。
ビルドして実際の出力を確認する。 次を実行します。
```
npm run build
npm run serve
```
レンダリングされた <head> を確認します。次のような icon link が含まれるはずです。
```
<link rel='icon' href='/img/favicon.ico'>
```
build/img/favicon.ico が存在し、Network panel が HTML ではなく image を返すことを確認します。baseUrl を設定している場合は、prefix を付けた URL を確認します。build/ ディレクトリ全体をデプロイしてください。

よくある落とし穴

src/img にファイルを置く: インポートしたアセットはアプリにバンドルされ、自動的に /img/ に公開されるわけではありません。この構成では static/ を使用してください。
baseUrl を考慮しない: baseUrl は config option で処理されますが、headTags に直接記載した icon URL は処理されません。
キャッシュされたタブを確認する: サイトをプライベートウィンドウで開くか、強制的にリロードしてください。レスポンスが正しいのにタブに古い内容が表示され続ける場合は、favicon troubleshooting checklist を使用してください。
icon link が重複する: 生成された head を調べ、theme や plugin によって追加された tag を確認してください。意図した SVG を1つ、ICO fallback を1つ残し、意図しない重複は削除してください。
一般的なワークフローを比較する: 共通 principles については、static-site-generator favicon guide と比較してください。Docusaurus 固有の要素は、favicon option と static/ output です。

結論

Docusaurus の favicon にページ単位のコンポーネントやプラグインは必要ありません。適切なファイルを生成し、static/img/ に配置して、favicon を ICO に指定してください。また、deployment または base path を変更するたびに、build 後の head を検証してください。

前提条件

5ステップで Docusaurus favicon を追加する

よくある落とし穴

結論

Docusaurus 向けの一貫したアイコンデータを用意