Guía para configurar un favicon en Docusaurus

Si el favicon de tu Docusaurus sigue mostrando el icono predeterminado del framework después de sustituir el recurso, puede que el archivo esté en la carpeta equivocada o que la configuración no apunte a él. Coloca el icono en static/, define el valor de configuración correspondiente y comprueba la salida del build.

Requisitos previos

Necesitas un proyecto de Docusaurus, una imagen fuente cuadrada y acceso a docusaurus.config.ts.

• Un PNG o SVG cuyo diseño siga siendo reconocible a 16×16 píxeles.
• Las dependencias del proyecto instaladas y una terminal abierta en la raíz del repositorio.

Añade un favicon de Docusaurus en cinco pasos

1. Genera los archivos adecuados. Usa Mzu favicondl para convertir un PNG o SVG cuadrado en un ICO y descarga después un SVG o PNG. Mantén simple el diseño de origen; un wordmark completo se vuelve ilegible en una pestaña.
2. Usa el directorio static/. Docusaurus lo copia en la salida del build sin modificar sus rutas internas. Sustituye el icono predeterminado o organiza tus archivos así:

   static/
   └── img/
       ├── favicon.ico
       ├── favicon.svg
       └── favicon-32.png

3. Usa la opción de configuración integrada. En el objeto existente de docusaurus.config.ts, mantén o añade:

   const config: Config = {
     // ...other options
     favicon: 'img/favicon.ico',
   };

   Usa una ruta relativa a static/, sin una barra inicial. La opción integrada añade el enlace al icono y aplica baseUrl, por lo que la configuración funciona tanto en la raíz de un dominio como bajo un subpath.

4. Añade un SVG si quieres un icono escalable. Añade esta propiedad al mismo objeto de configuración sin eliminar el fallback de ICO:

   headTags: [
     {
       tagName: 'link',
       attributes: {
         rel: 'icon',
         type: 'image/svg+xml',
         href: '/img/favicon.svg',
       },
     },
   ],

   La etiqueta sigue la relación de enlace rel='icon' de HTML. Como headTags son literales, incluye la ruta base: con baseUrl: '/docs/', usa /docs/img/favicon.svg.

5. Compila y comprueba la salida real. Ejecuta:

   npm run build
   npm run serve

   Inspecciona el <head> renderizado. Debería contener un enlace al icono como:

   <link rel='icon' href='/img/favicon.ico'>

   Confirma que build/img/favicon.ico exista y que el panel Network devuelva una imagen, no HTML. Si usas baseUrl, comprueba la URL con el prefijo. Despliega el directorio build/ completo.

Problemas habituales

• Colocar archivos en src/img: Los assets importados se empaquetan en la app; no se publican automáticamente en /img/. Para esta configuración, usa static/.
• Ignorar baseUrl: La opción de configuración se encarga de esto; las URL literales de los iconos en headTags, no.
• Revisar una pestaña con la caché: Abre el sitio en una ventana privada o fuerza una recarga. Si la respuesta es correcta pero la pestaña sigue desactualizada, usa la lista de diagnóstico del favicon.
• Enlaces de iconos redundantes: Revisa el head generado para detectar las etiquetas que hayan añadido un theme o un plugin. Conserva un SVG intencional y un ICO como fallback, y elimina los duplicados accidentales.
• Comparar otros flujos de trabajo: Para conocer los principios comunes, consulta la guía de favicon para static site generators; las partes específicas de Docusaurus son su opción favicon y el resultado en static/.

Conclusión

Un favicon en Docusaurus no necesita un componente a nivel de página ni un plugin. Genera los archivos correctos, mantenlos en static/img/, apunta la opción favicon al ICO y verifica el head generado después de cada despliegue o cambio de base path.