If you've ever deployed a MkDocs site and noticed the browser tab still shows a generic document icon instead of your brand, you're not alone. MkDocs generates static HTML, but it doesn't automatically pick up a favicon unless you tell it where to find one. This guide walks you through adding a favicon to your MkDocs project, step by step.
We'll cover the file placement, the HTML tags, and the common pitfalls that trip up developers. By the end, you'll have a crisp icon in every tab.
Prerequisites
Before you start, make sure you have:
A MkDocs project set up and building locally.
Access to your mkdocs.yml configuration file.
A favicon image file (PNG or SVG recommended). If you need one, you can generate it with Mzu favicondl.
Step 1: Prepare your favicon file
MkDocs serves static files from the docs/ directory by default. Create an img folder inside docs/ if it doesn't exist, and place your favicon there. For best compatibility, use a 32x32 PNG or an SVG. If you want to support older browsers, also include a favicon.ico at the root of your site.
Your structure should look like this:
docs/
index.md
img/
favicon.png
favicon.ico (optional, for legacy browsers)
Step 2: Configure MkDocs to use the favicon
MkDocs uses a theme to render pages. Most themes, including the default 'mkdocs' theme and popular ones like Material for MkDocs, allow you to set a favicon via the theme configuration in mkdocs.yml.
Open mkdocs.yml and add or modify the theme section:
theme:
name: material
favicon: img/favicon.png
If you're using the default theme, the configuration might look like:
theme:
name: mkdocs
favicon: img/favicon.png
This tells MkDocs to include the appropriate <link> tag in the HTML head. The exact behavior depends on the theme, but most themes follow this pattern.
Step 3: Add a fallback favicon.ico (optional)
Some browsers, especially older ones, request /favicon.ico by default. To avoid a 404 error, place a favicon.ico file in the root of your docs/ directory. MkDocs will copy it to the root of the built site.
You can create an ICO file from your PNG using an online converter or a tool like ImageMagick. For detailed steps, see our guide on PNG to ICO conversion.
Step 4: Build and verify
Run mkdocs build or mkdocs serve to build your site. Open it in a browser and check the tab. You should see your favicon. If not, inspect the page source to confirm the <link rel='icon'> tag is present and points to the correct path.
For a deeper check, use the browser's developer tools: go to the Network tab and look for the favicon request. A 200 status means it's loading correctly.
Common pitfalls
Wrong file path: The path in mkdocs.yml is relative to the docs/ directory. If you put the favicon in docs/img/favicon.png, use img/favicon.png.
Theme override: If you're using a custom theme, you may need to manually add the link tag in your template. Check your theme's documentation.
Caching: Browsers cache favicons aggressively. After updating, do a hard refresh (Ctrl+F5) or clear the cache. For more, see how to clear favicon cache.
Missing ICO: If you don't provide a favicon.ico, some browsers will show a 404 in the console. It's not critical but can be avoided.
Conclusion
Adding a favicon to MkDocs is straightforward once you know where to put the file and how to configure the theme. With the steps above, your documentation site will have a professional touch that helps users identify your tab instantly. Remember to test across browsers and keep your favicon file sizes reasonable for performance.
Check the documented requirements
The HTML Standard defines rel='icon' as the link relationship for an icon representing the current page.
ファイルの置き場所とテーマの設定方法を理解していれば、MkDocs に favicon を追加するのは簡単です。上記の手順どおりにすれば、ドキュメントサイトの見栄えがよくなり、ユーザーがタブを一目で識別できるようになります。異なるブラウザー间でテストし、パ Moose нужно favicon ファイルサイズが過大にならないよう管理することを忘れないでください。
ドキュメントに記載された要件を確認する
HTML Standard では、rel='icon' は、現在のページを表すアイコンの link relationship と定義されています。
MkDocs 사이트를 배포한 뒤 브라우저 탭에 브랜드 아이콘 대신 일반 문서 아이콘이 계속 표시된 적이 있다면, 흔한 상황입니다. MkDocs는 정적 HTML을 생성하지만 favicon의 위치를 알려 주지 않으면 favicon을 자동으로 적용하지 않습니다. 이 가이드에서는 MkDocs 프로젝트에 favicon을 추가하는 방법을 단계별로 살펴봅니다.
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단계: favicon을 사용하도록 MkDocs 구성
MkDocs는 테마를 사용해 페이지를 렌더링합니다. 기본 ‘mkdocs’ 테마와 Material for MkDocs 같은 인기 테마는 대부분 mkdocs.yml의 theme 구성을 통해 favicon을 지정할 수 있습니다.
mkdocs.yml을 열고 theme 구성을 추가하거나 수정하세요.
theme:
name: material
favicon: img/favicon.png
기본 테마를 사용하는 경우 구성은 다음과 같을 수 있습니다.
theme:
name: mkdocs
favicon: img/favicon.png
이렇게 설정하면 MkDocs가 HTML head에 적절한 <link> 태그를 포함합니다. 정확한 동작은 테마에 따라 다르지만 대부분의 테마는 이 방식을 따릅니다.
3단계: 대체 favicon.ico 추가(선택 사항)
일부 브라우저, 특히 오래된 브라우저는 기본적으로 /favicon.ico를 요청합니다. 404 오류를 피하려면 docs/ 디렉터리의 루트에 favicon.ico 파일을 배치하세요. MkDocs는 이 파일을 빌드된 사이트의 루트로 복사합니다.
PNG 파일은 온라인 변환기나 ImageMagick 같은 도구를 사용해 ICO 파일로 변환할 수 있습니다. 자세한 절차는 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를 사용하세요.
테마 오버라이드: custom theme을 사용하는 경우 템플릿에 link 태그를 직접 추가해야 할 수 있습니다. 해당 테마의 문서를 확인하세요.
캐싱: 브라우저는 favicon을 강하게 캐시합니다. favicon을 업데이트한 뒤에는 hard refresh(Ctrl+F5)를 수행하거나 캐시를 지우세요. 자세한 내용은 favicon 캐시 삭제 방법에서 확인하세요.
ICO 파일 누락:favicon.ico를 제공하지 않으면 일부 브라우저의 콘솔에 404 오류가 표시됩니다. serious한 문제는 아니지만 피할 수 있습니다.
마무리
파일을 배치할 위치와 theme 설정 방법을 알고 나면 MkDocs에 favicon을 추가하는 일은 간단합니다. 위 단계를 따르면 사용자가 탭에서 문서 사이트를 즉시 식별할 수 있어 전문적인印象을 더할 수 있습니다. 서로 다른 브라우저에서 테스트하고, 성능을 위해 favicon 파일 크기를 합리적인 수준으로 유지하는 것도 잊지 마세요.
문서화된 요구 사항 확인
HTML Standard는 rel='icon'을 현재 페이지를 나타내는 아이콘의 link relationship로 정의합니다.
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.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
Ruta de archivo incorrecta: La ruta en mkdocs.yml es relativa al directorio docs/. Si colocas el favicon en docs/img/favicon.png, usa img/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.
Need a Favicon for Your MkDocs Site?
Generate a perfect favicon in seconds with Mzu favicondl. Free, fast, and compatible with all browsers.