MkDocs サイトをデプロイした後、ブラウザーのタブには、ブランドのアイコンの代わりに、汎用的なドキュメントアイコンが表示されることがあります。同じ症状に当てはまるのは、あなただけではありません。MkDocs は静的 HTML を生成しますが、favicon の場所を指定しない限り、favicon を自動的に読み込みません。このガイドでは、MkDocs プロジェクトに favicon を追加する手順を段階的に解説します。
ファイルの配置場所、HTML タグ、開発者がよくつまずく落とし穴を扱います。最終的には、各タブに鮮明なアイコンを表示できます。
前提条件
開始する前に、次のものを用意してください。
- ローカルでセットアップしてビルドできる MkDocs プロジェクト。
mkdocs.yml設定ファイルへのアクセス権。- favicon 用の画像ファイル(PNG または SVG を推奨)。用意していない場合は、Mzu favicondl で生成できます。
ステップ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.yml内のパスは、docs/ディレクトリを基準とした相対パスです。favicon をdocs/img/favicon.pngに配置した場合は、img/favicon.pngを指定してください。 - テーマによる上書き: カスタムテーマを使用している場合、テンプレートに link タグを手動で追加する必要があるかもしれません。テーマのドキュメントを確認してください。
- キャッシュ: ブラウザーは favicon を強くキャッシュする傾向があります。更新後は、hard refresh(Ctrl+F5)を行うか、キャッシュを消去してください。詳しくは、favicon のキャッシュを消去する方法を参照してください。
- ICO ファイルの欠如:
favicon.icoを用意していない場合、一部のブラウザーではコンソールに 404 が表示されます。重要な問題ではありませんが、回避できます。
まとめ
ファイルの置き場所とテーマの設定方法を理解していれば、MkDocs に favicon を追加するのは簡単です。上記の手順どおりにすれば、ドキュメントサイトの見栄えがよくなり、ユーザーがタブを一目で識別できるようになります。異なるブラウザー间でテストし、パ Moose нужно favicon ファイルサイズが過大にならないよう管理することを忘れないでください。
ドキュメントに記載された要件を確認する
HTML Standard では、rel='icon' は、現在のページを表すアイコンの link relationship と定義されています。