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:
- Un proyecto de MkDocs configurado y que se compile localmente.
- Acceso al archivo de configuración
mkdocs.yml. - Un archivo de imagen favicon (se recomienda PNG o SVG). Si necesitas uno, puedes generarlo con Mzu favicondl.
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.pngSi utilizas el theme predeterminado, la configuración puede ser así:
theme:
name: mkdocs
favicon: img/favicon.pngEsto 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
- Ruta de archivo incorrecta: La ruta en
mkdocs.ymles relativa al directoriodocs/. Si colocas el favicon endocs/img/favicon.png, usaimg/favicon.png. - Anulación del tema: Si usas un tema personalizado, es posible que tengas que añadir manualmente la etiqueta link en tu plantilla. Consulta la documentación de tu tema.
- Caché: Los navegadores almacenan los favicons de forma agresiva. Después de actualizarlo, haz una recarga forzada (Ctrl+F5) o borra la caché. Para saber más, consulta cómo limpiar la caché del favicon.
- ICO ausente: Si no proporcionas un
favicon.ico, algunos navegadores mostrarán un 404 en la consola. No es crítico, pero puedes evitarlo.
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.