如果你部署过 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 等常用 theme,都允许你通过 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:添加备用 favicon.ico(可选)

有些浏览器,尤其是较旧的浏览器,默认会请求 /favicon.ico。为避免出现 404 错误,请将 favicon.ico 文件放在 docs/ 目录的根目录下。构建站点时,MkDocs 会将它复制到生成站点的根目录。

你可以使用在线转换器或 ImageMagick 之类的工具,从 PNG 创建 ICO 文件。有关详细步骤,请参阅我们的 PNG 转 ICO 指南。

第 4 步:构建并验证

运行 mkdocs build 或 mkdocs serve 来构建站点。在浏览器中打开它并查看标签页,你应该能看到 favicon。如果没有,请检查页面源代码,确认 <link rel='icon'> 标签存在,并且指向正确的路径。

如果需要进一步检查,可以使用浏览器的开发者工具:切换到 Network 面板,查找 favicon 请求。状态码为 200 表示它已正确加载。

常见陷阱

结语

了解文件放置位置以及主题配置方式后,为 MkDocs 添加 favicon 并不复杂。按照上述步骤,你的文档站点会增添一份专业感,帮助用户一眼认出标签页。记得在各种浏览器中进行测试,并将 favicon 文件大小控制在合理范围内,以保证性能。

核对文档要求

HTML Standard 将 rel='icon' 定义为用于表示当前页面图标的链接关系。