Docusaurus Favicon Setup: A Practical Step-by-Step Guide

If your Docusaurus favicon still shows the framework's default icon after you replace the asset, the file may be in the wrong folder or the config may not point to it. Put the icon in static/, set one config value, and verify the built output.

Prerequisites

You need a Docusaurus project, a square source image, and access to docusaurus.config.ts.

• A PNG or SVG whose mark stays recognizable at 16×16 pixels.
• The project dependencies installed and a terminal open at the repository root.

Add a Docusaurus favicon in five steps

1. Generate suitable files. Use Mzu favicondl to convert a square PNG or SVG into an ICO, then download an SVG or PNG. Keep the source artwork simple; a full wordmark becomes unreadable in a tab.
2. Use the static/ directory. Docusaurus copies it into the build output without changing its internal paths. Replace the default icon or arrange your files like this:

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

3. Set the built-in config option. In the existing object in docusaurus.config.ts, keep or add:

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

   Use a path relative to static/, without a leading slash. The built-in option adds the icon link and applies baseUrl, so the configuration works at a domain root or under a subpath.

4. Add SVG when you want a scalable icon. Add this property to the same config object while retaining the ICO fallback:

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

   The tag follows HTML's rel='icon' link relationship. Because headTags are literal, include the base path: with baseUrl: '/docs/', use /docs/img/favicon.svg.

5. Build and check the real output. Run:

   npm run build
   npm run serve

   Inspect the rendered <head>. It should contain an icon link like:

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

   Confirm build/img/favicon.ico exists and the Network panel returns an image, not HTML. With baseUrl, check the prefixed URL. Deploy the complete build/ directory.

Common pitfalls

• Putting files in src/img: Imported assets are bundled by the app; they are not automatically published at /img/. Use static/ for this setup.
• Ignoring baseUrl: The config option handles it; literal icon URLs in headTags do not.
• Checking a cached tab: Open the site in a private window or force a reload. If the response is correct but the tab remains stale, use the favicon troubleshooting checklist.
• Overlapping icon links: Inspect the generated head for tags added by a theme or plugin. Keep one intentional SVG and one ICO fallback, then remove accidental duplicates.
• Comparing broader workflows: For shared principles, compare the static-site-generator favicon guide; the Docusaurus-specific parts are its favicon option and static/ output.

Conclusion

A Docusaurus favicon does not need a page-level component or plugin. Generate the right files, keep them in static/img/, point favicon at the ICO, and verify the built head after every deployment or base-path change.