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:

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

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.