5 Docs-Site Favicon Mistakes (and How to Fix Them)
Docs sites fumble the favicon in a handful of predictable ways, almost always because the documentation lives on a different platform from the app and nobody owns its tab icon. Here are the five most common, in rough order of how often they show up, each with the quick fix.
The five mistakes
- 1
No docs favicon at all
The docs subdomain ships with nothing, so the browser shows a blank page icon and Google shows a globe. Fix: serve at least a single sharp square PNG plus a favicon.ico on the docs host.
- 2
The platform's default icon
The docs still wear Docusaurus's or GitBook's stock icon because nobody changed the setting. It's not even your brand. Fix: point the platform's favicon field at your own mark — five minutes, covered per-platform in the recipes.
- 3
Identical to the app
The docs use the exact same favicon as the app, so the two are indistinguishable in a tab bar full of both. Fix: keep the mark, add a coloured outline so docs tabs are catchable at a glance.
- 4
A blurry upscaled icon
A tiny logo stretched to fill the tab, soft and muddy at 16px. Fix: generate a real multi-size set from the source artwork instead of scaling one PNG; test it at true 16 and 32px.
- 5
A stale icon after a rebrand
The app got the new logo; the docs, on a separate deploy, still show last year's. Fix: regenerate both sets from one source in the same step, and add a CI check that downloads each host's favicon.
Why docs sites specifically get this wrong
Every one of these traces back to the same structural fact: documentation usually lives on its own subdomain and its own platform, outside the main app's codebase and its review process. The app's favicon gets attention because it's in the repo everyone touches; the docs favicon sits in a config file on a platform only the docs owner logs into. So it drifts, defaults, or never gets set.
The fix for the category — not just the individual mistakes — is to treat the docs favicon as an owned asset: generated from the same source as the app's, checked in CI, and updated in the same motion as any rebrand.
Test at the sizes that expose the mistakes
Docs favicon mistakes FAQ
What's the single most common one?
No docs favicon at all, closely followed by the platform's default icon. Both come from the docs living on a separate platform that nobody wired up. Fixing either takes minutes.
Is an identical-to-the-app favicon really a mistake?
It's the subtlest one, and it's still a real cost: in a tab bar with both docs and app open, identical icons force the user to read titles to tell them apart. Keeping the mark and adding an outline fixes it without touching brand.
How do I stop the stale-after-rebrand problem?
Generate the docs set from the same source mark as the app in one step, and add a CI check that fetches each host's live favicon and compares it to the expected bytes. Then a rebrand can't leave docs behind.