Quick answer
Commit the icon package inside the directory or branch published by GitHub Pages. A file omitted from that publishing source cannot be recovered by adding only a link tag.
- Last verified
- July 31, 2026
- Evidence
- Primary documentation plus a route-specific implementation example
- Primary sources
- 2
Project paths and constraints
Commit the icon package inside the directory or branch published by GitHub Pages. A file omitted from that publishing source cannot be recovered by adding only a link tag.
Project Pages sites publish below /repository-name/ unless a custom domain changes the root. Jekyll and other generators should use their base-url helpers for portable links.
Connected next stepCloudflare Pages Favicons: Assets, Headers and Cache for the closest prerequisite or comparison.
Declare favicon metadata once
For a custom domain or user site, root-relative paths are straightforward. Project sites commonly live below /repository-name/, so use the site generator’s base URL helpers or the correct prefixed asset paths.
Use relative_url or an equivalent generator helper for project Pages assets. A literal leading slash targets the github.io hostname root and skips the repository-name segment unless a custom domain owns the root.
Connected next stepVercel Favicons: Static Files, Rewrites and CDN Cache for the next connected implementation decision.
Build, deploy, and verify
Open the Pages deployment URL and custom domain separately, inspect their final head markup, and check capitalization because hosted asset paths are case-sensitive.
A leading /favicon.ico can work on a custom domain and fail on the github.io project URL. Test both deployment identities before selecting the final path strategy.
Connected next stepOpen the most relevant production tool and verify the decision with a working output.
Verify both Pages URL identities
Confirm the icon directory exists in the branch or Actions artifact selected as the Pages source. Inspect the published HTML at username.github.io/repository-name/ and follow its resolved icon URLs before introducing a custom domain.
After DNS and CNAME configuration are active, repeat the requests on the custom hostname. Record both final URLs and redirects; a path that is portable through a Jekyll baseurl helper should not depend on one deployment identity by accident.
Production file tree and code: GitHub Pages project-safe paths
Liquid's relative_url filter preserves the repository prefix on project Pages and also adapts to a custom domain. Keep the icon directory inside the selected Pages source.
assets/icons/
├── favicon.svg
├── favicon.ico
├── apple-touch-icon.png
└── site.webmanifest
_includes/head.html
_config.yml<link rel="icon" href="{{ '/assets/icons/favicon.svg' | relative_url }}" type="image/svg+xml">
<link rel="apple-touch-icon" href="{{ '/assets/icons/apple-touch-icon.png' | relative_url }}">
<link rel="manifest" href="{{ '/assets/icons/site.webmanifest' | relative_url }}">Review the headings, sources, implementation artifact, and update record for this guide as structured JSON.
Download guide evidence ↓- Guide
- GitHub Pages Favicons: Base Paths and Deployment
- Coverage
- Client behavior can change by browser, operating system, platform version, cache state and deployment configuration. Unperformed manual observations are not claimed.
Questions, answered
Why does /favicon.ico fail on a project Pages site?+
Project sites normally live below /repository-name/, so a hostname-root URL can point outside the published project. Use the correct prefix or a generator base-URL helper.
Does adding a CNAME publish missing icons?+
No. The icon files must already be in the selected Pages source. A custom domain changes the public hostname, not the contents of the deployment artifact.