MkDocs サイトをデプロイした後、ブラウザーのタブには、ブランドのアイコンの代わりに、汎用的なドキュメントアイコンが表示されることがあります。同じ症状に当てはまるのは、あなただけではありません。MkDocs は静的 HTML を生成しますが、favicon の場所を指定しない限り、favicon を自動的に読み込みません。このガイドでは、MkDocs プロジェクトに favicon を追加する手順を段階的に解説します。

ファイルの配置場所、HTML タグ、開発者がよくつまずく落とし穴を扱います。最終的には、各タブに鮮明なアイコンを表示できます。

前提条件

開始する前に、次のものを用意してください。

ステップ1: favicon ファイルを準備する

MkDocs はデフォルトで docs/ ディレクトリから静的ファイルを配信します。docs/ 内に img フォルダがなければ作成し、その中に favicon を配置してください。最大限の互換性を確保するには、32x32 PNG または SVG を使用します。古いブラウザーにも対応する場合は、サイトのルートに favicon.ico も追加してください。

構成は次のようになります。

docs/
  index.md
  img/
    favicon.png
  favicon.ico  (optional, for legacy browsers)

ステップ2: MkDocs で favicon を使うように設定する

MkDocs は theme を使ってページを描画します。多くの theme では、デフォルトの 'mkdocs' theme や Material for MkDocs などの人気テーマを含めて、mkdocs.yml の theme 設定で favicon を指定できます。

mkdocs.yml を開いて、theme セクションを追加または変更します。

theme:
  name: material
  favicon: img/favicon.png

デフォルトの theme を使用している場合、設定は次のようになる可能性があります。

theme:
  name: mkdocs
  favicon: img/favicon.png

これにより、MkDocs は HTML の head に適切な <link> タグを含めます。正確な挙動は theme によって異なりますが、ほとんどの theme はこのパターンに従います。

ステップ3: fallback 用の favicon.ico を追加する(任意)

一部のブラウザ、特に古いブラウザでは、デフォルトで /favicon.ico をリクエストします。404 エラーを避けるには、favicon.ico ファイルを docs/ ディレクトリのルートに配置してください。MkDocs は、そのファイルをビルドされたサイトのルートにコピーします。

PNG から ICO ファイルを作成するには、オンラインコンバーターや ImageMagick のようなツールを使えます。詳しい手順については、PNG から ICO への変換に関するガイドを参照してください。

手順4: ビルドして確認する

mkdocs build または mkdocs serve を実行してサイトをビルドします。ブラウザーで開き、タブを確認してください。favicon が表示されるはずです。表示されない場合は、ページソースを調べ、<link rel='icon'> タグが存在して、正しいパスを指していることを確認します。

より詳しく確認するには、ブラウザーの開発者ツールを使います。Network タブを開いて、favicon のリクエストを探してください。ステータスが 200 なら、正しく読み込まれています。

よくある落とし穴

まとめ

ファイルの置き場所とテーマの設定方法を理解していれば、MkDocs に favicon を追加するのは簡単です。上記の手順どおりにすれば、ドキュメントサイトの見栄えがよくなり、ユーザーがタブを一目で識別できるようになります。異なるブラウザー间でテストし、パ Moose нужно favicon ファイルサイズが過大にならないよう管理することを忘れないでください。

ドキュメントに記載された要件を確認する

HTML Standard では、rel='icon' は、現在のページを表すアイコンの link relationship と定義されています。