Si alguna vez has desplegado un sitio con MkDocs y has visto que la pestaña del navegador todavía muestra el icono genérico de un documento en lugar del de tu marca, no eres la única persona. MkDocs genera HTML estático, pero no detecta automáticamente un favicon a menos que le indiques dónde encontrarlo. Esta guía te explica paso a paso cómo añadir un favicon a tu proyecto de MkDocs.

Veremos dónde colocar el archivo, qué etiquetas HTML añadir y los errores más habituales que suelenatiable a los desarrolladores. Al terminar, tendrás un favicon nítido en cada pestaña.

Requisitos previos

Antes de empezar, asegúrate de tener:

Paso 1: prepara el archivo favicon

MkDocs sirve los archivos estáticos desde el directorio docs/ de forma predeterminada. Crea una carpeta img dentro de docs/ si no existe y coloca allí tu favicon. Para obtener la máxima compatibilidad, utiliza un PNG de 32x32 o un SVG. Si quieres兼容性 con navegadores antiguos, incluye también un favicon.ico en la raíz de tu sitio.

La estructura debería ser así:

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

Paso 2: configura MkDocs para usar el favicon

MkDocs utiliza un theme para renderizar las páginas. La mayoría de los themes, incluido el theme predeterminado 'mkdocs' y otros populares como Material for MkDocs, permiten configurar un favicon mediante la opción theme en mkdocs.yml.

Abre mkdocs.yml y añade o modifica la sección theme:

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

Si utilizas el theme predeterminado, la configuración puede ser así:

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

Esto le indica a MkDocs que incluya la etiqueta <link> correspondiente en el head del HTML. El comportamiento exacto depende del theme, pero la mayoría sigue este patrón.

Paso 3: añade un favicon.ico de respaldo (opcional)

Algunos navegadores, especialmente los más antiguos, solicitan /favicon.ico de forma predeterminada. Para evitar un error 404, coloca un archivo favicon.ico en la raíz del directorio docs/. MkDocs lo copiará a la raíz del sitio generado.

Puedes crear un archivo ICO a partir de tu PNG usando un conversor en línea o una herramienta como ImageMagick. Para ver los pasos detallados, consulta nuestra guía sobre conversión de PNG a ICO.

Paso 4: Compila y verifica

Ejecuta mkdocs build o mkdocs serve para generar tu sitio. Ábrelo en un navegador y comprueba la pestaña. Deberías ver tu favicon. Si no aparece, inspecciona el código fuente de la página para confirmar que la etiqueta <link rel='icon'> está presente y apunta a la ruta correcta.

Para una comprobación más detallada, usa las herramientas de desarrollo del navegador: ve a la pestaña Network y busca la solicitud del favicon. Un estado 200 indica que se está cargando correctamente.

Problemas comunes

Conclusión

Añadir un favicon a MkDocs es sencillo cuando sabes dónde colocar el archivo y cómo configurar el tema. Con los pasos anteriores, tu sitio de documentación tendrá un acabado profesional que ayudará a los usuarios a identificar tu pestaña al instante. Recuerda probar en distintos navegadores y mantener razonables los tamaños de tus archivos favicon para no perjudicar el rendimiento.

Comprueba los requisitos documentados

El HTML Standard define rel='icon' como la relación de enlace para un icono que representa la página actual.