Skip to content

fix: add multi-format favicons for consistent display on all pages - #271

Open
christy-dev4 wants to merge 1 commit into
Pidoko257:mainfrom
christy-dev4:fix/missing-favicon-223
Open

fix: add multi-format favicons for consistent display on all pages#271
christy-dev4 wants to merge 1 commit into
Pidoko257:mainfrom
christy-dev4:fix/missing-favicon-223

Conversation

@christy-dev4

@christy-dev4 christy-dev4 commented Jul 27, 2026

Copy link
Copy Markdown

Fix Missing Favicon on All Pages

Summary

The ProxyPay docs portal had no visible favicon in browser tabs, bookmarks, or on
mobile home screens. The root cause was two-fold:

  1. Wrong format — favicon was set to img/logo.svg. Many browsers (older Chrome,
    all versions of Safari on iOS/macOS, Windows taskbar/pinned-sites, and every version
    of IE/Edge Legacy) do not support SVG as a favicon source. They silently ignore the
    tag and display a generic blank icon.

  2. Missing fallback files — No .ico or .png favicon files existed in the repo,
    so browsers that support only those formats had nothing to fall back to.

Criterion Delivered
Favicon appears in browser tab ✅ favicon.ico (16 + 32 + 48 px) served via <link rel="icon" type="image/x-icon">
Works on all pages ✅ headTags injects into every page's <head> globally
Appears in bookmarks / home screen ✅ apple-touch-icon.png (180×180) for iOS/macOS; .ico for Windows
No console errors ✅ All referenced files exist; no 404s

Root Cause

// Before — SVG-only favicon; ignored by Safari, Windows, older Chrome
favicon: 'img/logo.svg',

Browsers select a favicon using <link rel="icon"> tags in the document <head>.
Docusaurus only injects one tag from the favicon config key. SVG icons are specified
in the WHATWG standard but browser support
is incomplete:

Format Chrome Firefox Safari Edge iOS Windows
.ico ✅ ✅ ✅ ✅ ✅ ✅
.png ✅ ✅ ✅ ✅ ✅ ✅
.svg ✅ (v80+) ✅ (v41+) ❌ ✅ (v79+) ❌ ❌

Without an .ico or .png fallback, Safari users (desktop and mobile) and anyone
saving the site on Windows see no favicon at all.

Changes

static/img/favicon.ico (new)

A multi-resolution ICO file containing three embedded PNG streams:

  • 16×16 px — browser tab (small)
  • 32×32 px — browser tab (retina / high-DPI)
  • 48×48 px — Windows taskbar / pinned site

Each frame renders the ProxyPay brand mark: a green rounded square
(#2e8555) with a white ₿ glyph — matching logo.svg.

static/img/favicon-32x32.png (new)

Standalone 32×32 RGBA PNG. Used by the <link sizes="32x32"> tag, which modern
browsers (Chrome, Firefox, Edge) prefer over .ico when both are present.

static/img/favicon-16x16.png (new)

Standalone 16×16 RGBA PNG. Fallback for environments that request small icons
explicitly.

static/img/apple-touch-icon.png (new)

180×180 RGBA PNG. Required by iOS Safari and macOS for:

  • "Add to Home Screen" icon
  • Safari bookmark thumbnails
  • macOS Dock if the site is opened as a web app

docusaurus.config.ts

Two targeted changes:

1. favicon field — changed from SVG to ICO so the automatically injected
<link rel="shortcut icon"> tag points at a universally supported format:

- favicon: 'img/logo.svg',
+ favicon: 'img/favicon.ico',

2. headTags array — five additional <link> tags injected into every page
<head>, giving browsers a full priority list to choose from:

headTags: [
  // Legacy browsers, Windows taskbar, IE
  { tagName: 'link', attributes: { rel: 'icon', type: 'image/x-icon',  href: '/proxypay/img/favicon.ico' } },
  // Modern browsers — 32×32
  { tagName: 'link', attributes: { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/proxypay/img/favicon-32x32.png' } },
  // Modern browsers — 16×16 fallback
  { tagName: 'link', attributes: { rel: 'icon', type: 'image/png', sizes: '16x16', href: '/proxypay/img/favicon-16x16.png' } },
  // iOS / macOS Add-to-Home-Screen
  { tagName: 'link', attributes: { rel: 'apple-touch-icon', sizes: '180x180', href: '/proxypay/img/apple-touch-icon.png' } },
  // Modern Chrome/Firefox — SVG (crisp at any DPI)
  { tagName: 'link', attributes: { rel: 'icon', type: 'image/svg+xml', href: '/proxypay/img/logo.svg' } },
],

The browser resolution order is:

  1. Picks image/svg+xml if it supports SVG icons (Chrome 80+, Firefox 41+).
  2. Falls back to image/png sized 32x32 or 16x16 for everything else.
  3. Uses image/x-icon as the universal last resort (IE, old Android).
  4. Uses apple-touch-icon when triggered by iOS/macOS bookmark actions.

How to verify

Dev server (visual check)

npm start
# Open http://localhost:3001 in:
#   Chrome  → should see the green ₿ icon in the tab
#   Safari  → should see the green ₿ icon in the tab
#   Firefox → should see the green ₿ icon in the tab
# Bookmark the page → icon should appear in bookmarks bar

Check <head> tags

Open DevTools → Elements → <head>. You should see all five <link> tags:

<link rel="icon" type="image/x-icon"  href="/proxypay/img/favicon.ico">
<link rel="icon" type="image/png" sizes="32x32" href="/proxypay/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/proxypay/img/favicon-16x16.png">
<link rel="apple-touch-icon" sizes="180x180" href="/proxypay/img/apple-touch-icon.png">
<link rel="icon" type="image/svg+xml" href="/proxypay/img/logo.svg">

No 404s

Open DevTools → Network → filter by favicon — all five requests should return
200 OK with appropriate Content-Type headers.

All pages

Navigate between / and /api — the favicon should persist on both pages
(Docusaurus injects headTags globally, so this is guaranteed).

Notes

  • No new runtime dependencies.
  • No changes to any React component or page layout.
  • The pre-existing webpack ProgressPlugin build warning is unrelated to this PR
    (present on the base branch before these changes).
  • Image files are small (< 800 bytes each) and committed directly to static/img/
    following the existing project convention for logo.svg.

closes #223

@christy-dev4
fix: add multi-format favicons for consistent display on all pages (P…
28cc43e 
…idoko257#223)

Root cause: favicon field pointed to logo.svg which is silently ignored
by Safari (all versions), iOS, Windows taskbar, and older browsers.
No .ico or .png fallback files existed.

Changes:
- Add static/img/favicon.ico (16/32/48 px multi-resolution ICO)
- Add static/img/favicon-32x32.png (32x32 RGBA PNG)
- Add static/img/favicon-16x16.png (16x16 RGBA PNG)
- Add static/img/apple-touch-icon.png (180x180 RGBA PNG for iOS/macOS)
- Update docusaurus.config.ts:
    - favicon field: 'img/logo.svg' → 'img/favicon.ico'
    - Add headTags with 5 <link> tags covering ico, png-32, png-16,
      apple-touch-icon, and svg for complete cross-browser coverage

Browser resolution order: svg (Chrome/Firefox) → png-32 → png-16
→ ico (IE/legacy) → apple-touch-icon (iOS/macOS bookmarks)

closes Pidoko257#223
@drips-wave

drips-wave Bot commented Jul 27, 2026

Copy link
Copy Markdown

@christy-dev4 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Fix Missing Favicon on All Pages

1 participant

@christy-dev4