Can’t make my .svg favicon show up on GitHub pages or locally?

by

Summary

This incident centers on a Safari-specific limitation: older Safari versions simply do not support SVG favicons, regardless of how correct the HTML markup is. The engineer spent time debugging paths, cache, and GitHub Pages configuration, when the real blocker was browser capability, not code.

Root Cause

The root cause was using Safari 18.x, a version that does not support SVG favicons at all.
No amount of HTML tweaking could make the favicon appear.

Contributing factors:

  • Safari’s historically inconsistent favicon support
  • Aggressive favicon caching, even after manual deletion
  • Conflicting online documentation, much of it outdated
  • GitHub Pages serving SVGs correctly, but Safari ignoring them

Why This Happens in Real Systems

Real systems fail in this way because:

  • Browser feature support is uneven, especially around newer formats like SVG favicons.
  • Developers assume “latest version” but run older builds, especially on macOS where Safari updates are tied to OS updates.
  • Caching layers hide changes, making it appear as if the markup is wrong.
  • Documentation online lags behind browser behavior, leading to contradictory advice.

Real-World Impact

This type of issue causes:

  • Wasted engineering hours debugging a problem that cannot be fixed in code.
  • False assumptions about deployment, caching, or file paths.
  • Unnecessary refactoring of HTML, folder structure, or asset pipelines.
  • Loss of confidence in GitHub Pages or the developer’s own setup.

Example or Code (if necessary and relevant)

A correct SVG favicon reference (for browsers that support it) looks like this:

This is valid. The issue was not the markup.

How Senior Engineers Fix It

Senior engineers approach this by:

  • Checking browser support first, before debugging markup.
  • Testing in multiple browsers to isolate whether the issue is client-side or server-side.
  • Using feature support tables (MDN, CanIUse) to confirm compatibility.
  • Falling back to PNG/ICO for maximum compatibility:
    • favicon.ico at the root
    • Optional favicon.png for high‑res displays
  • Avoiding premature assumptions about caching or path issues.

A robust cross-browser setup:

Why Juniors Miss It

Junior engineers often miss this because:

  • They trust that “latest browser” means actually up-to-date.
  • They assume all browsers behave the same with modern formats.
  • They over-focus on HTML correctness, not platform capability.
  • They don’t test across multiple clients early in debugging.
  • They believe conflicting online advice, not authoritative compatibility data.

The key takeaway: Sometimes the system is correct — the browser isn’t.

Leave a Comment