If you host a site on GitHub Pages, favicon setup seems simple until it is not: one browser shows the new icon, another keeps the old one, your custom domain behaves differently, and a clean SVG works in one place while a legacy tab still asks for an ICO. This guide gives you a reusable checklist for GitHub Pages favicon setup, including practical patterns for SVG and ICO support, cache refresh steps, and custom domain considerations you can revisit whenever your theme, build workflow, or browser support needs change.
Overview
A GitHub Pages favicon setup is really a small deployment workflow, not just a single file upload. You are managing three things at once: the icon files themselves, the HTML references that tell browsers what to use, and the caching behavior that can make a correct implementation look broken.
For most GitHub Pages sites, the safest approach is straightforward:
- Create a simple favicon that remains legible at very small sizes.
- Export at least an SVG and a fallback ICO or PNG.
- Place the files where your site generator or static output will publish them consistently.
- Add explicit
<link rel="icon">tags rather than relying on browser guesses. - Test on the GitHub Pages URL and on the custom domain, if you use one.
- Use a versioned file name or query string when replacing an existing icon.
This matters for more than appearance. The favicon is one of the smallest identity assets on your site, but it shows up in browser tabs, bookmarks, pinned interfaces, reading lists, and shared browsing contexts. On a developer portfolio, docs site, project page, or personal knowledge base, a clear favicon supports recognition and reduces the “generic template” feel. If you are aligning it with a broader identity system, it helps to keep it consistent with your avatar and site branding; see Personal Website Branding Checklist: Match Your Favicon, Avatar, Domain, and Social Profiles.
Before you start, decide which GitHub Pages setup you have:
- A plain static site in the repository root
- A Jekyll site using layouts and includes
- A site built by another static site generator, then published to Pages
- A project site under a repository path
- A user or organization site at the root domain
- A site with a custom domain
That single decision affects pathing, file placement, and how you test the final result.
Checklist by scenario
Use the scenario below that matches your GitHub Pages setup. The goal is to avoid path issues first, then deal with format and cache behavior.
Scenario 1: Plain static GitHub Pages site
This is the simplest case: HTML files live in the published directory and you are not depending on a theme engine to inject head tags.
- Put your favicon files in the published root, such as
/favicon.svg,/favicon.ico, and optionally/apple-touch-icon.png. - Add explicit tags inside the
<head>of every page, or in a shared template if you have one.
<link rel="icon" href="/favicon.svg" type="image/svg+xml">
<link rel="alternate icon" href="/favicon.ico" sizes="any">
<link rel="apple-touch-icon" href="/apple-touch-icon.png">If your site is a user or organization site published at the domain root, absolute paths like /favicon.svg are usually appropriate. If you later move to a project site under a subpath, revisit these URLs.
Scenario 2: Jekyll site on GitHub Pages
With Jekyll, the favicon problem is often not file generation but template placement. You may add the files correctly and still fail to load them if your layout head section is not rendering the links where you expect.
- Store the files in a location Jekyll will publish unchanged, commonly the site root or an assets folder.
- Add the icon tags in your default layout head.
- If your site may run under a subpath, use Jekyll filters or variables to build correct URLs.
<link rel="icon" href="{{ '/favicon.svg' | relative_url }}" type="image/svg+xml">
<link rel="alternate icon" href="{{ '/favicon.ico' | relative_url }}" sizes="any">The key point is that relative_url can help when the site base URL is not root. This is especially useful for repository project pages.
Scenario 3: Project site under a repository path
A common source of broken favicons on GitHub Pages is using root-relative paths on a site that actually lives at something like https://username.github.io/repository-name/.
Checklist:
- Do not assume
/favicon.icopoints to your project site root. It points to the domain root. - Use your generator’s base path helper or write the full repository subpath explicitly.
- Open DevTools and confirm the favicon request is going where you think it is going.
In many cases, the icon works locally but fails on GitHub Pages because local dev serves from root while production serves from a subdirectory. If you only remember one GitHub Pages favicon rule, make it this one: check the final deployed path, not the local preview path.
Scenario 4: Site built with another static site generator
If you use Eleventy, Hugo, Astro, VitePress, Docusaurus, or another generator and deploy the output to GitHub Pages, treat favicon setup as part of the build contract.
- Place favicon files in the source location that gets copied to output without modification.
- Confirm whether your tool rewrites asset URLs based on base path settings.
- Add icon links in the shared head template or config hook your generator supports.
- After build, inspect the generated HTML in the output directory, not just the source template.
Many favicon bugs are really build pipeline bugs. The file exists, but the generated HTML points somewhere else, or the base path changes between preview and production.
Scenario 5: SVG-first favicon with ICO fallback
This is a practical modern default for many developer sites. SVG gives you crisp rendering and small-file flexibility for simple artwork, while ICO remains a useful fallback for older or inconsistent environments.
Use this checklist:
- Make sure the SVG artwork is simple and readable at very small sizes.
- Avoid tiny text, fine outlines, and low-contrast shapes.
- Keep a fallback ICO available.
- Reference both formats explicitly in the head.
- Test the icon in light and dark tab environments if your design depends on contrast.
If your mark is complex, an SVG favicon may still be technically valid but visually weak at tab size. In that case, create a simplified favicon-specific mark rather than reusing the full logo. For that design step, see How to Create a Favicon From a Logo Without Losing Clarity at 16x16.
Scenario 6: ICO-first compatibility approach
If you want a minimal, conservative setup, a single favicon.ico in the site root can still work well, especially for plain static sites. This is useful when your site does not need a broader icon set and you want fewer moving parts.
Checklist:
- Create an ICO containing multiple sizes if your export tool supports it.
- Place it in the published root.
- Add an explicit link tag anyway, even if some browsers may find it automatically.
<link rel="icon" href="/favicon.ico" sizes="any">This does not prevent you from adding SVG later. It just gives you a stable baseline.
Scenario 7: Custom domain on GitHub Pages
Custom domains add one more testing layer. Your GitHub Pages site may work at the default github.io address and still show a missing or stale favicon on the custom domain.
Checklist:
- Verify the favicon file is being served correctly on the custom domain, not just on the GitHub Pages URL.
- Check that your icon links use paths appropriate for the custom domain structure.
- If you use a CDN or proxy in front of the custom domain, confirm it is not serving a stale icon.
- Keep the icon references consistent after domain changes, subdomain moves, or HTTPS enforcement changes.
For example, a root-relative path may behave differently depending on whether the site is at a root domain, subdomain, or repository path. When in doubt, test the actual network request from the production domain.
What to double-check
Once the files are deployed, this is the review pass that saves the most time.
1. File location
Open the direct URL to each file. Do not just trust the repository tree. Confirm that the published site serves:
favicon.svgfavicon.icoapple-touch-icon.png, if used
A file sitting in the repo is not enough; it must exist in the built output where GitHub Pages serves it.
2. HTML head output
View source on the live page and check that the icon tags are present in the final rendered HTML. This matters because theme templates, includes, and generators sometimes override or omit head content.
3. Correct paths for your site type
If the site is under a repository path, make sure your links are not accidentally pointing to the domain root. If the site is on a custom domain, make sure the paths still make sense after the domain mapping.
4. Cache behavior
Browsers can hold on to favicon files longer than you expect. If the new icon does not appear:
- Hard refresh the page.
- Open the site in a private or incognito window.
- Test in a second browser.
- Rename the favicon file, such as
favicon-v2.icoorfavicon-2026.svg. - Update the HTML to point to the new file name.
Changing the file name is often more reliable than replacing the file in place. If you want a deeper workflow for this situation, see Favicon Not Showing? A Troubleshooting Checklist for Browsers, CMSs, CDNs, and Mobile Devices.
5. Fallback logic
If you use SVG, verify that your fallback file also exists and is linked correctly. A broken fallback can be invisible during your own testing if your browser prefers SVG and caches it aggressively.
6. Platform-specific extras
If your site is also used as a PWA or pinned home screen site, your favicon is only part of the icon picture. Revisit your broader icon set, including maskable and touch icons, if relevant. Related guides: Maskable Icons Explained, PWA Icon Requirements Checklist, and Apple Touch Icon Guide.
7. Brand consistency
A working favicon can still be the wrong favicon. If your GitHub Pages site supports a portfolio, documentation hub, or personal project identity, compare the final icon with your avatar, social profile image, and Open Graph image. The assets do not need to match exactly, but they should feel related. For that distinction, see Open Graph Image vs Favicon vs Avatar: What Each Identity Asset Does for Your Brand.
Common mistakes
These are the failure patterns that show up repeatedly in GitHub Pages favicon work.
Using only one untested format
Relying on a single PNG or SVG without checking real browser behavior can leave gaps. A dual-format setup is often safer unless you have a reason to keep things minimal.
Assuming root-relative paths always work
This is the classic project-site mistake. A path that begins with / may bypass your repository subpath entirely.
Editing the repo but not the generated output
On generated sites, changing source files is not the same as publishing correct output. Always inspect the deployed build result.
Replacing a favicon file without changing its name
This can make you spend an hour debugging a cache issue that is not really a code issue. Versioned file names are a practical habit.
Using a detailed logo that collapses at 16x16
A favicon is not a miniature homepage header. It needs high contrast, simple geometry, and clear negative space. If the favicon is part of your identity system, treat it as its own design problem.
Forgetting the custom domain test
Do not stop after the icon works on the default GitHub Pages URL. If the public site uses a custom domain, that domain is the real test environment.
Ignoring broader trust signals
For personal brands, developer products, and public project pages, visual consistency matters. An outdated or generic favicon can make a maintained site feel neglected. During a larger identity review, it is also worth checking for copycat use of your icons and related brand signals; see Brand Impersonation Checklist.
When to revisit
This setup is worth revisiting whenever the underlying conditions change. Keep this as a short maintenance checklist:
- When you change themes or templates: head markup may move or be overridden.
- When you switch generators or build tools: asset paths and output rules often change.
- When you move from a project site to a custom domain: path assumptions and caching behavior should be retested.
- When you redesign your brand: favicon clarity at small sizes should be checked separately from larger logos.
- When you add PWA features: revisit the full icon set, not just the browser tab icon.
- Before seasonal planning cycles or portfolio refreshes: test that the site identity still matches your current public presence.
A practical action plan is simple:
- Open your live site on the production domain.
- Inspect the head tags in page source.
- Open the direct URLs for the icon files.
- Test in at least two browsers and one private window.
- If the icon changed recently, version the file name and redeploy.
- Compare the favicon with your current avatar and site branding.
If your visual identity has changed more broadly, revisit your favicon alongside your profile picture and domain presentation rather than treating it as an isolated task. These related guides can help: How Often Should You Refresh Your Favicon or Profile Picture? and Personal Website Branding Checklist.
The main takeaway is that a reliable GitHub Pages favicon setup is less about one perfect file and more about a repeatable workflow: correct paths, explicit tags, tested fallbacks, and a deliberate cache refresh strategy. If you keep those four pieces in place, future favicon changes become routine instead of frustrating.