Jekyll Favicon Guide: Add Icons Without Breaking baseurl

A Jekyll favicon can build successfully and still break when the site uses a baseurl: the asset lands in a nested path, but the HTML points to the domain root. Keep source files in a static directory, generate URLs through Jekyll, and inspect the built output before publishing.

Prerequisites

• A Jekyll project with editable layouts or includes.
• A square SVG, an ICO fallback, and optionally a 180×180 PNG. Mzu favicondl can create these from one image.
• Local access to bundle exec jekyll build.

Add a Jekyll favicon in five steps

1. Create a permanent source folder

   Add favicon.svg, favicon.ico, and apple-touch-icon.png to assets/images/. Never edit _site/; Jekyll recreates that directory during the next build.

2. Add links to the document head

   Open your theme’s _includes/head.html and insert these tags before its closing head element. If the theme has no include, place them directly in _layouts/default.html. Confirm that the layout still calls {% include head.html %}.

   <link rel='icon' type='image/svg+xml' href='{{ '/assets/images/favicon.svg' | relative_url }}'>
   <link rel='icon' sizes='16x16 32x32 48x48' href='{{ '/assets/images/favicon.ico' | relative_url }}'>
   <link rel='apple-touch-icon' sizes='180x180' href='{{ '/assets/images/apple-touch-icon.png' | relative_url }}'>

   The HTML specification defines rel='icon' for an icon resource. Keeping the links in the head lets the browser discover them while parsing the page.

3. Generate baseurl-aware URLs

   Set baseurl in _config.yml to match the deployment path. Then run every icon path through Jekyll’s relative_url filter. It prefixes the configured base path, so the template works at the domain root and under a project subpath. Do not hard-code href='/assets/images/favicon.svg', because it ignores that subpath.

4. Build and inspect the generated site

   Run the build and local server:

   bundle exec jekyll build
   bundle exec jekyll serve

   Open _site/index.html and confirm that each link includes the expected base path. Check that the three files exist under _site/assets/images/. For the preview, use the baseurl-aware URL printed by Jekyll instead of assuming the site starts at /.

5. Verify the deployed response

   After publishing, inspect the page source and request an icon URL directly. The page must reference the deployed path, and the icon request must not return a 404. If the old mark persists, rename the file or add a query such as favicon.svg?v=2. The favicon troubleshooting guide covers cache-specific checks.

Common pitfalls

• Editing generated files: changes in _site/ disappear on the next build.
• Ignoring baseurl: root-relative paths can request the icon from the wrong location.
• Keeping duplicate links: a theme icon and your custom icon can compete. Remove the unwanted link from the rendered head.
• Placing markup in the body: move the links into the head include or layout.

Conclusion

With assets under assets/, links in your reusable head template, and URLs generated by relative_url, your Jekyll favicon moves cleanly from source to production. For format choices and broader tag examples, read the HTML favicon guide.